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MACHACK 2001 


By Andrew S. Downs 


Ls rr Over Already? 

What just happened? 

MacHack 2001 (also known as MacI lack 16) is now just 
a backed-up date b<x>k entry in my Palm Vit, but strong 
memories remain. This was the most successful MacHack 
ever in several categories: a record number of attendees, a 
record number of papers presented, the firs!-ever Lego 
Mindstorms sessions track, a maximum number of student 
registrations, the longest Hack Contest ever (six hours), the 
largest keynote address (a panel of seven), and the first-ever 
Fireside Chat w ith Steve Wozniak. 

What is this MacHack Thing? 

If you have never heard of MacHack, lei me try Lo explain: 
it is the Macintosh developer's conference with “underground 
cred" (per ZDNet eWEEK: wwwzd net .com/e week), three-plus 
clays of mostly technical sessions presented by the people who 
write the software you use every day, cap[xreboff by a rousing 
display of showmanship and programming ability known as 
the Hack Contest, which is sponsored by The MacHax Grouf> 
(wwvv.macbax.com). 

Due to the round I lie-clock programming effort and 
accompanying lack of sleep, many attendees take a while to 
decompress from the experience. Although 1 slept more this 
year than previously, it still look several days of thinking 
about what Vd seen (and done) to put tilings in perspective. 
As usual. I did not attend as many sessions as l would have 
liked, but I enjoyed everything I did attend, 

Record-Setting Keynote Discussion 

Hie conference traditionally opens with a keynote address 
at midnight of the first day. The keynote this year consisted of a 
panel of seven memlxrs of die original Macintosh development 
team: Hill Atkinson, Andy HeitzfekJ, Jef Raskin, Caroline Rose, 
Donn Denman, Dan Kottke, and Randy Wigginton. 
Programming legend and author Scott Knaster worked the 
mien.)phone as moderator, getting the discussion started and 
keeping things moving. Each of the panel members first told the 
tale of how he or she had come to be on the Macintosh team 
Even if you have read various accounts elsewhere, there is 
something authentic about hearing die stories firsthand, 

I am sorry Lo say I didn't make it through the whole- 
keynote this year, I saw Jef Raskin in the elevator the next 
morning and he said he hadn’t made it back to his room 
until after 6am! 


Lego my, cm. Lego 

This year I made sure to get a peek at some of the 
Yool sessions, specifically the ones focused on Lego 
Mindstorms, The sessions I attended were presented by 
Dave Baum. (There were adult Mindstorms sessions too. TF 
you arc unfamiliar with the Mindstorms concept, take a 
look at Matthew Nathan's article in the May 2001 issue of 
MacTech.) I was impressed with the ability of these young 
hackers, and I'm sure some of them cart program circles 
around me, The Mindstorms sessions were held in one of 
the conference rooms, with four sets of robot parts lo hack 
with and four iMaes for writing the control programs. 

After a brief overview of the robot hardware and the 
programming environment (using a C-like language and 
compiler), the Yoots were walked through some simple 
programs that demonstrated l>oth how Lo make the robot 
move in various directions for a certain length of time, and 
also how to use the optical sensor to determine proximity. 
Then, the hard part: the instructor tasked the kids with 
writing a program that enabled the robot to follow a curved 
track, stopping upon reaching the end. The track was a strip 
of gray tape laid upon while poster hoard. This was rio easy 
feat, but I think all of the kids in that session managed to 
make it work. Anti yes, l did help out a little. What can 1 
say. lx>Lh the Yoots and the robots are pretty fun! 

J attended another {>1 Daves sessions, this one geared 
toward adults. We I tad tire same task as the Yoots: write a 
program to make the robot follow a line on the ground. In 
the true spirit of MacHack, Dave made it a competition: the 
robots would be timed during their traversal of the course, 
and the fastest finisher would be declared the winner* 
Obviously there was more to this than '"go forward for 
three... 7 seconds". I hud the good sense to team up with 
Jesse Donaldson from Palm Computing, and we spent some 
time improving upon a simple algorithm for moving the 
robot until it sensed a change in the track via the optical 
sensor. Upon sensing a change, the robot had to continue 
to follow the track, but with only one sensor this involved 
a fair amount of trial and error. Our entry eventually took 
second place after Jesse did some additional optimization; 
Dr, Waldemur Horvvat finished first. 

You cun expect to see Mindstorms at MacHack again next 
year, maybe with a twist. 


Andrew Downs is a four-time MacHack attendee* putting him somewhere above i>al*e-in-amis" and below "grizzled veteran", Let s just say he really 
enjoys the conference. Andrew works for Snippets Software, writing Internet apps for the desktop and PDAs Andrew also teaches programming courses 
Ul Tulane University College in New' Orleans, tA You can reach him at arulrew^downs.ws. 
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Emulation 

1 attended two sessions on emulation this year. Eric TrauL 
from Connectix (wwwxonnectixxom) spoke about Virtual PC, its 
evolution and some of the cool things being done in the latest 
release. Eric also discussed Connectix' newest product, Virtual 
PC for Windows. This is one of the most well-attended 
sessions at each conference. Eric is a terrific speaker, and 
casually and politely talks tech stuff with the audience rather 
than aL them. These sessions always inspire me. 

Darek Mihocka from Emulators Inc. (www.emulators.com) 
also presented a session on emulation, but from a different 
angle: running Mac OS on Windows. Darek discussed some 
of the issues involved with emulating both the 68K and 
PowerPC instruction sets using the x8b architecture (quite a 
challenge!) After accuracy, die biggest issue is speed, and 
Darek provided some insight into how an emulator can run 
as fast as the real thing. Ouch! 

Other Fun Stupe 

A couple of other sessions that I enjoyed included Dave 
Koziols Palm development overview, and Mail Morse's 
IleaderDoc discussion. Dave did a good job of single- 
handedly carrying the Palm track this year, assisted to some 
degree by the two Palm papers presented at the conference. 
Two features that make Palm development fun are its 
emphasis on small programs, and the fact that it is very Mac- 
like (which is no accident, given its pedigree). 

IleaderDoc is Apple’s open source header file 
documentation generator. I arrived late for this session, but 
had a g<xxl discussion with Mart afterward. That is another 
hallmark of the conference: you can have one-on-one 
conversations with engineers from Apple (and other 
companies) about the tools you use everyday. 1 contributed 
some bug fixes to HeaderDoc earlier liiis year, and this was the 
first time I physically met anyone else involved on the project. 

And the Award for Bkst Paper Goes To... 

Papers are one of the cornerstones upon which the 
conference is built. This year thirteen papers were presented, 
covering a wide variety of topics including information 
reliability, Palm development, data alignment, color image 
conversion, data sharing, OS X, scripting Cocoa, frameworks, 
and REALbasic development. The paper voted Best of Show 
was Fan Oilman’s “Practical Altivec Strategies”. In return Ian 
gets to attend next year’s Mad lack without paying the 
conference registration fee. Thanks lan! 

The Hack Contest 

The sessions are a prelude to the hack contest on 
Friday night, starting at midnight. Here all of the hard 
work of the previous year (or several hours, if you get a 
late start) comes together, This year witnessed a record 
number of hacks presented at the contest, and though not 
all of them worked well (if at all), it reinforced the 
cutting-edge spirit of the conference. Over the past few 


years a growing number of Yoot hacks have been 
submitted, and this year i noticed what seemed to be a 
larger number of collaborative hacks. In fact, the winning 
hack (Apple Turnover) was a collaboration between Mac 
Murrell and Allon Stern. Apple Turnover rotates the image 
on your main display in real-time. Needless to say, editing 
a document then becomes very challenging! 

Many of the hacks are Mac OS user interface related, 
since that allows for a high-level of showmanship, which 
is an important part of your presentation at Sam. Both 
Classic and OS X are represented. There are also a variety 
of videos, scripts, and Palm OS hacks; liiis year's contest 
also saw the first Mindstorms hacks. The hacks arc 
available on the conference CD; point your browser to 
vvwwjnachack.com for more info. 

But, I Missed It! 

If you were unable to attend this year, cheer up. Like many 
good things, Mad lack will come again. In die meantime, buoy 
your spirits by visiting the MacHaek website (www.machack.com) 
and picking up a copy of the conference CD (which contains 
the hacks, sessions, and papers), browsing the press releases 
and conference information from this year, and dreaming about 
how much fun it will l^e in 2002. And start thinking about an 
entry for die Hack Contest. See you there! K5? 
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By John C. Welch 

WWDC 2001 


A peek inside the Apple 

Welcome to the Show 

The 2001 Apple World Wide Developer Conference is 
finished, anil for those of us who were there, it was quite the 
whirlwind of activity and information. Like any other WWDC, 
this is the best chance for developers and technical people 
on the Mac to get a l<x)k inside the OS and the hardware, and 
to talk to the folks who make both. What was different about 
this session was the focus. No longer were the sessions alxnu 
things that were about to ship, things that hadn't happened 
yet. No great charts alx>ut proposed shipping schedules. This 
was about the present, not the future, and it was almost all 
about Mac OS X, 

When l say almost, I mean that discounting feedback 
forums, there were perhaps a handful of sessions that didn’t 
explicitly talk about Mac OS X. It was a refreshing change of 
pace too. No ‘maybe 1 , + will\ or l may\ Just + are and lias’. So, 
from that point of view, there were no earth shattering 
surprises. Which is just as well, as the last thing a programmer, 
or an IS manager wants to hear is surprise. That's not to say 
the conference was dull as dirt, but that you could pretty 
much anticipate wliat you were going to be seeing. My only 
real regret was that I had to miss all of Friday's sessions, and 
that I couldn't temporarily duplicate myself. 

The Keynote 

As all of you have seen and heard by now, the WWDC 
2001 keynote was less of a revelatory one, and more of a 
lecture, Steve said it point blank, if you don’t have your 
applications running native in Mac OS X P then your 
customers will find applications that are. This was not exactly 
taken well by some, but then again, harsh news rarely is. 
Now, some say Steve may have gone overboard with the 
finger shaking on this point, but maybe not. There are some 
folks, namely Adobe that have not only barely released a 
Carbon product, (Acrobat Reader is the I test they can do?), 
but have been completely silent on even a vague schedule 


for when we can expect anything else. I understand about 
things like Acrobat and Photoshop that need scanner support, 
but tilings like GoLive and Illustrator should be almost done, 
or if Macromedia is any example, at least one of Lhem should 
lie done by now. But the point was made. The time is now 
to gel product out there into the hands of the folks who write 
the checks, or someone else will come along and take your 
money. Apple understands painfully well how fickle loyally 
can be in the computer market. 

Not all was lecture and doom and gloom though. Jobs 
announced that the next version of Mac OS X Server was 
shipping, now sporting the Aqua interface, and taking its 
place as the server version of Apple’s OS family, litis version 
is also the product that marries the best of both the previous 
Mac OS X Server, and AppleSharcIP. The other announcement 
was that as of May 21st, all Apple computers will ship with 
both Mac OS X, and Mac OS 9.1 installed, although Mac OS 
9.1 will be the default boot OS. 

This decision has I seen greeted by a curious range of 
emotions, ranging from those who think it is a complete 
mistake, to those who thing that it’s an excellent idea. For 
myself. I’m somewhere in the middle, I think that Mac OS X 
still needs a lot of work in areas that haven’t received as much 
press as the popular, yet somewhat inconsequential CD - 
burning/DVD Playback Things like the fact that if you put 
your PowcrBook to sleep without an external monitor or 
keyboard, when you wake ii up, ir dcx j .sn'i recognize those 
things until you iebcjot, or that PC Card support is still 
ridiculously spotty. The lack of AppleScript support in the OS 
seems to not get a notice either. 

Still, I think thru Apple needed to do this. It allows Mac 
OS X to truly be a shipping OS, and it says that Apple has 
enough confidence in the OS as it stands to really put it out 
in the world. By making the default Ikxh OS Mac OS 9.1, it 
also allows the period Ixivvceri the WWDC and MacWorld 
Expo New York, to f>e a transitional one, giving folks time to 
get used to the tact that Mac OS X really is the future, and that 
it really is going to lx* the shipping OS for Apple. If Apple can 
get Mac OS X updated enough by July for MacWorld, then 


John Welch <jweld^compknemac.com> is 1 mining Specialist for Complete Mac Seminars, ihe leading MacOS instructional company. He has over 
fifteen years of experience ai making computers work. His specialties are figuring out ways to make the Mac do what nobody thinks it can, and helping 
other folks learn how to do those tilings for themselves. 
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making it the default OS for all Macs shipping after that event 
will not be as traumatic, or new. 

A third keynote announcement was that WebObjects 5, 
now 100% Java was shipping. While of more interest to 
commerce, and large database web site developers, it still has 
implications for all technical users, developer or other This 
is Apple saying that Java is not only a peer language with 
Objective C, but that it is the only language for Apple's 
biggest application server, ft is, for Apple, a commitment to 
Java as a language and a platform forgetting work done, that 
in its own way, rivals the Java commitment of such 
companies as IBM. It's also an example of Apple "eating its 
own dog foodl They have been saying since the first 
introduction of Mac OS X, that the OS wall lx* one of, if not 
the premiere Java platform. By making WebObjects a Java - 
only environment, they are lotting a huge part of Mac OS X 
on their ability to pull that off. Having played with some 
various Java applications that either cm terribly, or noL at all 
in Mac OS 9.X, J don't think its going to he hard to pull off. 

The final announcement was that Apple would no longer 
lx* shipping CRT monitors. This was not a real surprise, 
although the 17" LCD display that Sieve introduced was greeted 
w ith great enthusiasm. Apple lias lieen heading towards LCDs 
faster than any other computer company, and by ekninadrtg all 
external CRT monitors, (leaving the (Mac as the sole CRT 
product in the lineup), Apple lias managed to simplify their 
inventory a bit. This also will save them some overhead on 
shipping, as a 21" CRT is neither light, nor cheap to ship. 

There were of course, some product demos, such as 
Adobe Premiere, showing off some of its new features, and 
how making a movie under Mac OS X means you don’t 
have to kill virtual memory, or networking. When it gets 
around to shipping, it should be a neat product. Micromat's 
Drive 10 utility was demonstrated, showing* for the most 
part, that even a utility can have an elegant, functional 
interlace. There was a really nice demonstration of the 
native release of Macromedia's Freehand 10, The demo 
was run by Macromedia’s Vice President of Marketing, Tom 
Hale* He announced that Mac OS X had allowed them to 
get performance improvements of tip to 50% in some 
operations. The demo also made Job’s point about getting 
the Mac OS X native versions out there, especially to 
Adobe. Unlike Photoshop, which is still the dominant 
player in it's space, Illustrator and Freehand have always 
been close competitors, with Illustrator’s main advantage 
being llie close integration it has with Adobe’s other 
products* But between Freehand 10, and the upcoming 
native version of Canvas 8, Adobe could see Illustrator's 
market share drop if they can t have it shipping by July. 
Dominique Goupii, of FileMaker Inc* also ran through a 
dog and pony show of the newly carbonized FileMaker Pro 
5.5. Although a database will get more than most 
application types from the plumbing in Mac OS X, they 
added a very neat feature, namely new- support for PDF 
files* By integrating the native PDF support in Mac OS X 
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with the QuickTime capabilities of FileMaker Pro, you can 
now 'play' PDF files in a FileMaker database as though they 
were QuickTime movies. Considering that PDF is now the 
de facto standard for document exchange and archiving, 
Lliis ability gives FileMaker quite a feather in its bonnet. 
The final demo was of Tony Hawk's skateboarding game, 
Jt T s a neat game, but still seems to resemble Quake wiih a 
skateboard. The only thought this left me with is that ever 
since the rise of Quake, Tomb Raider, and Myth, most 
computer games seem to be variants on those basic 
archetypes. Hopefully, this will change soon. 

The Meat of thf. Wffk 

WWDC is hard to talk about sometimes because Lhcre 
is just so much information to handle. Even accepting that 
I just can't be in all the sessions I want to be in, there is 
si til enough to make one's brain hurt. 

Almost all the sessions were packed almost to capacity. 
No one, it seems, can get enough information on Mac OS 
X, and Apple was dishing it out in quantity. Some sessions 
had enough information, that the Q&A periods were held 
out in the hallways. The only session 1 was at that wasn’t 
jammed full was the Tech Docs Feedback forum. This was 
particularly amusing lo me, as one of the most consistent 
complaints about Apple is in this very area, yet the 
attendance doesn't reflect this. In any case, this was, as 
were the rest of the sessions, well worth the time taken. 
The Lech docs folks not only were able to show where they 
had made progress on issues raised in the past, but also 
had a clear roadmap of where they were going. They said 
all the right things, but not just pro forma. There was a 
definite ring of sincerity to what they were saying, and the 
Fact that they could point to definite improvements helped 
a lot here as well. Many issues surrounding non-developer 
technical documentation are being handled in what looks 
like the correct manner, that is, by ha ruling that area over 
to the [Services folks, who are also in charge of certification 
and technical training on Mac OS X and Mac OS X Server, 
Although il may seem odd to praise a passing of the buck' 
as ii were, the fact is, by ensuring that the proper groups 
are handling the different documentation areas, we, as the 
users of this documentation, get a better product that is 
more focused on our needs. 

Another perennial capacity forum is the 'Meet the VPs’ 
feedback forum. This is where attendees get a chance to be 
in the same room as the folks who head up the major 
groups at Apple, and talk to them directly. Comparing this 
year to sessions in past, the responsiveness is getting better 
each year, and the folks who came in from NeXT seem to 
be 'getting' the Mac more each year. Concerns about 
AppleScript were acknowledged, and for the first time, the 
NeXT folks were just as emphatic that AppleScript will be 
receiving the attention if needs to be the same tool as ii is 
in Mac OS 9- This is important to many developers and 
technical people, as there have been, and still are fears that 


the NeXT folks don't ‘get 1 the Mac, and don't want lo get 
the Mac. By having those people take the lead in correcting 
this, a lot of fears can be calmed down. There are 
feedback forums at the WWDC for almost every area of the 
Mac OS, and they are almost all well attended. As one of 
the forum panel folks told me after a particularly emotional 
session, Apple values the good and the bad feedback, 
especially die passionate feedback. Developers only get 
passionate about an OS they care about, not one they are 
about to dump. So Apple realizes that they cannot afford 
to ignore, or not listen to a developer that gets a little 
carried away in the heat of the moment. 

The technical sessions I attended were ail well done, 
and well thought out The information was presented in 
an interesting fashion, and considering how dry API 
explanations can be, the fact that these folks make ii 
interesting shows the amount of care put into the WWDC 
by Apple, One of the amusing things for me was watching 
the student and open source developers realize that when 
Apple says it doesn’t discuss unannounced products, it 
isn't kidding. Although this may seem to be an oxymoron 
for a developers conference, there’s some sense there. 
Things are always changing, patches are always being 
released, etc. If Apple spends large amounts of time on 
what may happen in the future, they aren't spending time 
talking about what developers need to know for what Is 
shipping now. While finding out tidbits about new 
sparklies on the horizon is cool, given the choice between 
talking about soon and now, I’ll take now. 

This focus was a good ihing, especially considering the 
sheer volume of information presented. Many of the sessions 
included excellent advice on optimizing application 
performance, specific code examples, etc. Even better, since 
all of this information was about shipping products, it was 
all stuff that we can use here and now, not at some 
unspecified point in the future, and it might change. When 
Apple said, this is the API Lo use for this functionality, and 
here's where ail the details are, it was nice to know that it 
wasn't all going to change overnight. Which Is what we have 
all needed on Mac OS X for a while now . Reliable, accurate, 
detailed information. Js Apple 100% of where they need to 
he for now? No, but they are much closer than they were last 
year Progress always heals stagnation, especially when 
talking about documentation. 

Conclusion 

1 know that Fm not going into excruciating detail about 
session content, etc. But then, all of what was said at the 
conference is available from Apple online, or via email. What 
is different, and what cannot Ixj replicated in any article is the 
value one gets from bouncing ideas off of Apple engineers, 
and other developers. You have to be there for that. Tf you are 
in a post Lion where you need technical information on die 
Mac and the Mac OS, then you need to be at the WWDC. It's 
a lot of work, and a lot of fun, G5Q 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonslra , Westford , AM 


Down-IN-Out 

George Warner earns two Challenge points for suggesting 
another interesting board game, this time tlie solitaire game 
known as Down-N-Out* 'fhe D own-N-Out board is a 10x30 
rectangular array cif cells, initially populated randomly with 100 
cells of each of three colors. The object is to score as many points 
as possible by removing cells from the board, A cell can be 
removed if it is adjacent (horizontally or vertically, but noL 
diagonally) with a cell of the same color When a cell is removed, 
all cells connected to it by transitive adjacency are removed. That 
is, all adjacent cells are removed, and all cells adjacent to those 
cells, etc. The number of points earned for cadi move is equal to 
die square of die number of cells removed (e.g., 2 cells = 4 
points, 3 cells = 9 points, etc), There is an obvious advantage to 
planning moves that maximize the number of connected cells 
removed simultaneously. After each move, the board is 
compacted by sliding all cells downward to fill any empty cells, 
and ihen by sliding all columns to the center to fill any empty 
columns. The game continues as long as cells can be removed. 
For those of you interested in trying the game, there is a 
shareware version available at 
<http://www.pedvaxom/software/downout,shtml>. 

The prototype for the code you should write is: 

typcd c. f char Ce 1 XColor: /* 0=cmpty, l..numColors .<re valtd ooli>rs V 
void InitDownNOuU 

short boardSizeRows . p number of rows in the gsmie 7 
short boardSizeCoIs, /* number of columns in the game 7 
short mimColors T P number of colors in the pine 7 

WindowEtr wdw p window where result* of your moves should he displayed 7 

>: 

void Band let! pda ieEvent (KventRecord thrEvont); 

Boolean P able to play 7 P1 a yOne D ownN Ou t Mov e £ 

Ceil Col or board [J . p board | ru wlioardSizeCols + col] is color of cell at 
Irowllcoll 7 

long score. P points earned prior to this move 7 

short 'raoveRow, p reiutti row of your next move 7 

short *oovgCo1 p return col of your next move 7 

); 

void TermDawiiNOut [void) ; 

Each game begins with a call to your InitDownNOut routine, 
Where you are given the dimensions of the game board 
(boardSizeRows and boardSizeCols), the number of colors in the 
game (numColors), and a pointer (gameWindow) to a 
Window Record where you must display the game state as it 
progresses, Finally, you will be given the initial si ale of the game 
board, fully populated with equal numbers of each color cell, 
subject to rounding limitations* InitDownNOut should allocate any 
dynamic memory needed by your solution, and that memory 
should be returned at the end of the game when your 
TermDownNOut routine is called 


Your PlayOneDownNOutMove routine will be called 
repeatedly, once for each move you make. You will be given 
your current point score as calculated by the test code and the 
state of the game board. You should determine the most 
advantageous move and return it in moveRow and moveCoi You 
should update the game board, eliminating cells removed by your 
move and compacting the board vertically and then horizontally. 
You should calculate the number of cells removed and return it 
in numberOfCellsRemoved. 

The last time we ran a Challenge that involved maintaining 
a display, contestants asked how the window would be redrawn 
in response to an update event* This time, Fm asking you to 
write a routine to do that. Your HandlellpdateEvent routine will 
be called by the Lest code whenever an update event is received 
for your gameWindow, 

During the call to InitDownNOut. and after each of your moves, 
you should display the updated game state in the gameWindow. 
The details of the display are tip to you, as long as the display 
correctly and completely represents the state of the board 

The winner will be the best scoring entry, as determined by 
the sum of i he point score of each game, minus a penalty of 1% 
for each millisecond of execution time used for that game. The 
Challenge prize will be divided between the overall winner and 
the besi scoring entry from a contestant that has noi won the 
Cha! I e nge recent 3 v. 

This will lie a native PowerPC Challenge, using the 
CodeWarrior Pro 6 environment. Solutions may be coded in C or 
C++. Fve deleted Pascal from the list of permissible languages, 
both because it isn't supported by CW6 (without heroics) and 
because no one has submitted a Pascal solution In a long time. 

Threr Months Ago Winner 

Congratulations to Ernst Mu tiler (Kanata, Ontario, 
Canada) for submitting the best scoring solution in the April 
Crossword II Challenge. This Challenge was inspired by a 
classroom exercise to construct a 20x20 crossword puzzle 
using [lie names of the elements in the periodic table, valuing 
each word according to the atomic number of the 
corresponding element, with the objective of maximizing the 
total value of the puzzle* We generalized the problem by 
making the word list, word values, and puzzle size parameters 
of the problem. And to incorporate the usual emphasis on 
efficiency, we penalized each test case by 1% for each minute 
of execution time required to generate the puzzle. 

The winning solution starts by assigning a strength value 
to each word in the word list. The strength of a word is a 
scaled version of die value assigned by the problem input, 
divided by die length of a word. This heuristic favors shorter 
word*s of a given value over longer words of the same value* 
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Then tilt* Board::Solve routine tries to place words uniil a time 
limit (set to 15 seconds) expires or there are no more valid 
moves to explore. The moves are attempted in order of 
decreasing value, where the value of a move is the assigned 
value of word being placed, divided by the length of the word 
minus the number of letters that intersect other words. Again, 
this gives priority to placement of shorter high value words 
over longer ones, and to placements that efficiently use the 
hoard space by intersecting other words. 

I evaluated the four entries received using a set of ten test 
cases ranging in size from 20x20 to 50x50, Ernst's solution 
packed 10% more word value into his puzzles than the second 
place entry by Ron Nepsund, taking significantly more 
execution lime as well. For the original 20x20 problem based on 
the periodic table* Ernst’s entry produced the following 
crossword, valued at 2470 points: 
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Frnst would have won by an even wider margin were it not 
Ibr an ambiguity in the problem statement. The problem 
specified that each word could only occur once in the puzzle, 
and that each sequence of letters in the puzzle had to form a 
word. What I meant to say, however, but didn't, was that each 
word in the puzzle needed to lx: distinct. Two of the contestants 
uxik advantage of this loophole, fur example, to claim credit for 
the word "lirf embedded in the longer word “actinium^ 
Fortunately for my sense of fairness if nothing else* when 1 ran 
the tests both allowing and not allowing the loophole, the scores 
were such that the ranking of the entries was unchanged. The 
results as presented reflect the actual wording of the puzzle, and 
allow a word to lye embedded in another word 

As the best-placing entry from .someone who has not won 
a Challenge in die past two years. Ron Nepsund wins a share 
of this month's Challenge prize. You don't need to defeat the 
Challenge points leaders to claim a part of the prize, so enter the 
Challenge and w in Developer Depot credits! 

The table below lists, for each of the solutions submitted, 
the number of points earned by each entry, and the total time in 
seconds. It also lists Lite code size, data size, and programming 
language used for each entry. As usual, the number in 
parentheses after the entrant's name is the total nutnlxrr of 


Jtir.Y 2001 • MacTecii 


Program micros Challenge 





















Tri-platform Calendaring 



OSX Carb&r 

Mac OS 7 9.x 

Windows 95-2000 



CalendarMonster i .2 

Multi-platform calendar 



• End-user Calendar 

The best FMP calendar experience 

- Fast, fast, fast!!! 

- Platform-appropriate user experience 

- Highly scalable 

• Excellent Developer Support 
Quickly and easily integrate 
with your FileMaker Pro projects 


Challenge points earned in all Challenges prior to this one. 


Name 

Putins 

Time 

Code 

Data 

Ling 



(sees) 

Sbx. 

She 


Ernst Munter {731) 

52378 

151.4 

3940 

m 

C++ 

Ron Ncpsund (47) 

47489 

6.7 

44520 

mi 

C++ 

Jan Scholium (7) 

41888 

32,9 

12708 

m 

C++ 


Ken Skzak 126MLATE1 1927997,4 3160 r C+ + 


Top Cootrstani's ... 

Listed here are the Top Contestants for the Programmers 
Challenge, including everyone who has accumulated 20 or more 
points during die past two years. The numbers Ixdow include points 
awarded over die 24 most recent contests, including points earned 
by tills months enlranLs, die number of wins over the past 24 
months, and die total number of career Challenge points. 


Rank 

Name 

Points 

Wins 

Total 



(24 mo) 

(24 mo) 

Points 

L 

Munter, Kmst 

304 

L2 

751 

2. 

Rickere Willckc 

83 

3 

134 


.S.ixmn, Tom 

76 

2 

185 

4. 

Taylor, Jonathan 

56 

2 

% 

5. 

Shearer, Rub 

55 

1 

62 

6. 

(hes 

49 

2 

49 

7, 

Maurer, Sebastian 

48 

1 

108 


... and the Top Contestants Looking for a Recent Win 

In order lo give some recognition to other participants in 
the Challenge, we also list the high scores for contestants who 
have accumulated points without taking first place in a 
Challenge during the past two years. Listed here are all of those 
contestants who have accumulated 6 or more points during the 
past two years. 


- 100% live data, 100% modular, no plug-ins 

- FileMaker Pro 4 or 5 (including 5.5) 

- As tittle as 2 ScriptMaker calls 

- Dedicated developers 1 utility 
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Total 

a_ 

Boring. Kandy 

32 

M2 

<L_ 

Sc hoi,Minin. Jan 

14 

i < 

It), 

Sac Id sky, Gregory 

12 

14 

ii. 

Nepsund. Ronald 

10 

57 

12, 

Day, Mark 

10 

30 

i.-i 

[ones. Dennis 

10 

22 

14. 

Downs. Andrew 

10 

12 

15. 

Dupt Brady 

10 

_10_ 

Hi 

Fazekas, Miklos 

10 

10 

17, 

Flowers, Sue 

10 

10 

IS 

St rout, Joe 

10 

10 

19, 

Nicolle. Ludovic 

7 

55 

20. 

Ha la, l-adislav 

7 

7 

21. 

Miller, Mike 

7 

7 

22. 

Widvatama, Yudhi 

7 

7 

23. 

lleithcock. JG 

<> 

+2 


MacTecu • July 2001 











































































/e Built the 

Missing 


Messaging &: Queuing 


Need a 

Better 

Software 

Communication 

Solution? 


Middleware 

Mac 






hjiiva 


wwwjiiva.com/rapidmq 


, Inc. 


©2001 Jiiva, Inc. All rights reserved Jiiva. Inc . the Jiiva logo, vrtvwjiiva.corn RapidMO. and Middleware tor tee Mac are trademarks Of Jliva, fnc. 
Mac and rhe Mac logo are trademarks of Apple Computer, lnc„ registered in the US. and other countries. 

The "Buitt for Mac OS X" graphic is a trademark of Apple Computer, Inc., used under license. 
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• Real-time data synchronization 
allows data to be cached in 
memory for fast access. 
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Consumer Software 


• Automatically collect registration 
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There are three ways to earn points; (1) scoring in ihe top 
5 of any Challenge, (2) being the First person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that 1 use. The points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

A points 

5th place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


Here is Ernst’s winning Crosswordll solution: 


Crossword! Lcp 

Copyright © 2001 

Ernst Munter, Kunata, ON, Canada 

r 

Task 

Make a crossword puzzle from a set of supplied words, The l wist is: different 
words have different point values, ami the object b to maximize the point count. 

SolniiiHi 

The words arc wined according to * strength', that b the normalized point 
count - pointVTcngth. 

A search tree is huili using the most promising placements, up to a maximum 
of kMaxMovcs, at each stage 

To avoid atiy significant point penalty (of \% ptT minute), pressing stops 
after IS seconds. 

A private copy of the puzzle is huili where each cell is an unsigned character, 
with value of ti,< H or 2Y. An empty cell is 0, an placing a word is done 
by aikling each of the word’s character into the corresponding cell Similarly, 
removal of a word is done with subtraction. 

7 

finclude <std!ib.h> 
flinclude <£tring.h> 
jjfincliide <ctype.h> 

#include <Kv^ntn,h> 

^include "CrosswordTT 

typedef unsigned long ulong; 
typedef unsigned short, ushort; 
typedef unsigned char uchar; 

static int N“0: 

enum 1 

kDowu " 0, 
kAcross - 1. 
kHaxHoves “ 5, 
kTieksPerSecond - 60. 
kMasfSeconds - 15 
I; 


struct My Word 

struct MyWord 
// In capsulation of Words 
1 

const Words* word; 
ulong length; 

ulong sr r engrh:// lengtlvreLitive value 

bool used; 

MyWordU 11 

HyWord(const Words* up) ; 
word Cwp). 


length (strlentwp >theWord)l, 

strength UOx I GGCQL*wp >vuluo) /O+length) 1, 

used(false) 

(J 

const Words* WordO const I return word;] 

const char* Chars0 const I return word - HheVord: I 

long Valued const (return vord->value:! 

int LengthO const Ircturn length: I 

bool IsAvailableO const (return limed; | 

void SetUsedU fused ® true;! 

void ClearUsedO I used - false;! 

ulong StrengthH const (return strength:! 


static int CaipWord(const void* a,const void* b) 

f 

MyWord* ap~(MyWutd*)a; 

MyWord* bp K (MyWord*)b; 

return bp-Strength - ap->strengih: 


struct MyMovc 

//A Move b a pbeemou of a word 

1 

MyWord* w: 
ulong value: 
ushort row: 
ushert col: 
ushort delta; 

Ushort size; 

ulong Valued const (return value;! 

ulong Points {} const: {return w->word*>value: ] 

Void Unit(int mimlnlerscctSiMyWord* wx* 

int r,lnt c.iat d,int s) 

I 


*r“wx: 

value”(Oxl0000 * w>word->value) I 

(1 ivOLengthO ' numlntersects); 

row=r; 
col=c; 
deita^d: 
s i zs=s ; 

I 

void Clear () IvalueK); J 

ul ong TsValidO const ( return value: 7/l=M) 

void Convert(const Words* words,WordPositions* p) 

// Converts this instance ofMyMove' k> a Ward sit ion "as defined in 

//’Cmsswordil.h’ 

l 

p - ywhichWord^W’ >word -vo rd s: 
p->row=row: 
p >cd1”co1; 

p >o r ientaf i on= (del ta=l 1 ?kAcross: kDowu; 

I 

void kemoveWordfchar* puzzle] 

{ 

char* p^puzzie+row'size+col; 
char * str=w->word->theWord: 
for tint i-0:i<v >Length();i++) 

t 

*p -= *str++; 
p+=deHa: 

1 

w->ClearUsed(); 

I 

void PlaceWord(char* puzzle] 

1 

cha r * p-puzzlsf row * sit e+c 0 1: 
char* str”w >word->theWord; 
for (int i=0; i<w-^Length!!) ;1H) 

I 

*p += *str++; 

p+^eitar 

1 

w >SetUsed(}; 


int Intersect Ac ross (KyWord* w.lnt r,int c« 
char* puzzle,int puxzleSize) 


I 


// returns l(no fii) T 0 (fit, no intersects) tir n>0 (n intersects with other words) 


// insertion point p 
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Top 10 Reasons 

Why You Should Buy 
Funnel Web* 

10. It’s the most accurate Web site visitor analysis tool available 

9. Everyone should own at least one product named after the 
world’s deadliest spider 

8. One of the developers once worked in the gear room of the 
world’s highest aerial tram 

7. Buy the product and we’ll let you keep the CD 

6. It produces reports so beautiful you’ll want to carry them 
around in your wallet 

5. It runs on Mac, Linux, Windows, FreeBSD and Solaris 


4. Someone needed to start a new trend 


3. Thousands of your colleagues are already using it 

2. It’s 400% faster than competing products* 

And the #1 reason why you should try Funnel Web Analyzer is... 

(What, you think we’re going to give it up on the first date? 
Go to www.quest.com/top 10 to find out!) 


* Refers to e recent independent revie lv from Neiger Computer Consulting, 



QUEST 

SOFTWARE 


www.quest.com 



United States 1.949.754.8000 • Germany +49.211.770967.0 • United Kingdom +44.1628.601000 • France+331.4131.96 96 • Australia +61.3.9811.8000 






char* p^puzzle+r'puzzleSize+c; 
int Ien = v?->LengthO; 

// cell before the word must be a border or blank 
char* rowSta rt=puz zle+r *puzzleSize: 
char* cellBefore=p‘1; 

tf ((cel IBefore >“ rowStart) kk (0 ! = ‘rellBcfore)) 
return 1; 

// cell after the word must be a border or blank 
char* rowEnd=rowStart+puzzleSize: 
char* celiAfter^p+len: 

if ((cellAfter < rovEnd) kk (0 !“ *cellAfter}) 
return -li 


U all cells to the side of the word must be 

// (a) cither blank 

// lb} or pan of a crossing word 

// we know case b applies onEy if die cell the current word is 

// to occupy is already occupied - with a letter equal to str|x| 


char* str=w->word->theWord; 

char* puzzleKnd~puz7!e+puzzleSIze*puzz1 eS'i mi 

int nunlntersectEFOi 

for (int i a =0;i<len:i++.str-H‘,£rH-) 

I 

if (*p == 0) // crossing a bfrok 

I 

// cell above must be outside border or blank 

char* eel 1 Above-p-puxzleSize: 

if ((cell Above >“ puzzle) kk (0 1 cell Above)) 

return -1; 

// cell below must Esc outside bonier, or blank 
chat * eellBelow^p+puzzleSize: 

if ((cellBelov < puzzleEnd) kk (0 1= *cellBeIov}) 
return 1: 

I else If {* p ra * a t r) // crossi ng a word, match i ng 

t 

numlntersectS’H"; 

) else // crossing, but no match 
return -1; 

} 

] 

InitfmmlnLerset ts, w,r ,c*l .pitzzleSize): 
return numlntersects; 


int I n t e r s ectDovn(MyWord* w p int r,int c, 

char* puzzle,int puzzleSize) 


I 


// returns -Ifnn III), 0 (fit, no intersects) or o>0 (n intersects with other wonts) 


// insertion point p 

char 1 p=puzzle+r*puzzleSize+c: 
int ien=w->Length(): 

// cell before the word must lx: a border or blank 

char* colStart=puzzleIc; 
char * eellBefore^p-pnzz]eSize; 

If ((cel 1 Before >" col Start) kk (0 E= *cclIbeforej) 
return 1; 


// cell after tlic word must be a bonier or blank 

char* bottomBordef-puzzle+puzzieSize‘puzzlaSize; 

cha r * cellAfte t=pllen'puzzleSize; 

if fJcteHAfter < bottomEnrder) kk (0 1= ‘cellAfter}) 
return -1: 


// all cells to the side of the word must be 

if (a) either blank 

// (b) or part of a crossing word 

// we know case b applies only if the cell the current str would 
// occupy is already occupied - with a letter equal to sir|x} 

char* str^w >word >theWord; 

ebar* puzzleEnd^puzzle+puzzleSixe* puzxIeSize; 

char * leftEdge^puzzle+r‘puzzieSize; 

int numlntersectsK): 

for (int i-D; i<len; 

i++* str+t, pi ^puzzieSize,lef tEdgel-puzaleSisse) 

f 

if (*p = 0}// crossing a blank 


I 

// cell on die left must be die left border, or blank 
char* cellLeft=p-l ; 

if C(ceilLeft >- leftEdge) kb (0 != *cellLeft)) 
return -1: 

// cell on right mast he on the right edge, i>r blank 

Char* C0llRigbt'p+1 l 
char* ri ghtEdge^Ie f tEdg«+puzz 1 eSi z e; 
if ((trellRight < right Edge) kb (U 1= *ceIlRight)) 
return -1; 

1 else if (*p ™ *str}// crossing a word,matching 

I 

muni nte r s ect S++; 

] else// crossing, but no match 

1 

return -1; 

) 

1 

Init (numlntersects ,\t. t,c,puzzieSize.puzzieSize): 
return numlntersects; 

1 

I: 


typedef MyMove* MyMoveFtr: 

inline bool operator > (const MyMove & a,const MyMove k b) 

I 

return a.ValueO ) h.Value0; 

] 


struct MyMoveArray 

struct MyMoveArray 
i 

int numMoves; 
int maxMoves: 

MyMove moves [kftaxffoves]; 

MyMoveArray (lm max) : 
mtmMoveu(0)* 
maxMoves(max) 

0 

int NumMoves() const I return. numMoves;I 
MyMove* Moves 0 I return moves:! 

VO ift Insert (MyMove k ki) 
t 

if (numMoves=0) 

1 

numMoves=l: 
moves [ OJ “tn; 

1 else if (numMoves<maxMoves) 

I 

M y M o v t* * ii x =mo v e s+n umHu v e s; 

while [ Cmx)moves) kk (‘(msl) ^ m]J 

I 

*rax-*(rax*l); 

■ 1; 

*mx=iD; 

numMoves+f; 

] else if fm > moves[numMoves 1]) 

i 

numMoves-; 

Insert (tn): 


I 

I? 


struct Board; 


struct Board 


long puzzieSize; 
char* puzzle; 
long nutnWords: 

MyWord* myWords: 
long nunFositions: 
WordPositions* bestPositions; 


MyMove * 
MyMove* 
MyMovePtr* 
MyMoveFtt * 
MyMovePtr* 


move Fool: U single pool allocated for inovdists 
endMovePool; 

move Stack: // move stack tracks the history- of executed moves 

moveStackPointer; 
lastMoveStaek: 
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Board (long pSize*const Words* words, long nWords) : 
puzzleSize(piJize) , 
puzzle(new char[{pSlz«} 1 (pSlze)J), 
numWords(nWords)* 
myWordsfnew MyWord [nWords])» 
numPoair ionFi (0) * 

bestPost!ions[new Wot■dPositionri[rmmWords]}* 


movePool(tiew MyMove [numWords * kMaxMovesJ), 
endMovePoo 1 (rsovePoo 1+numWords * kMaxMoves), 
movaStack(new 

MyHovePtr fnouiWords]) .moveStackPointer (moveStack), 

lastMovaStacktiBibvcStack+nuriiWdrds- 1 ) 

I 

for (long i=C: i<mimWortls; i++) 
myVJords L ii-MyWord{words+i); 

// sort words by strength 

qrsort (myWord5 t nunWordrs.sizeof (MyWord) *CmpWord) ; 

// remove all U value words 

long i=mjnWordaj 

while ((i>0) &lt [luyWordsJi-1].Value{}<=G)J 
i-i-1: 

numWotths=i; 

I 

~fioa rd () 

E 

delete [] bestPositions; 
delete LI myWords: 
delete [I puzzle: 

I 

void Cl ear(} 

I 

I vv. 1!■, 0, s i zeOf {rba r) ‘ tpu ?.?. leSI m ) * (puzz 1 eSIze)) : 

I 

int Solve(const Words 1 words,WordPositions* positions): 

void SetPosition(const Words* words.MyWord* v.WordFositions* 
pas. 

int row,int col*int o) 

t 

pos >wblchWord-w >Word() words: 
pos >row=row: 
pos->col^col: 
p o s ■ > o r i entatio n =^o : 

I 

void FushMove(MyMove* mp)E 
‘movoStaekPo t nt or++=nip; 


MyMove * PopMove(} 

! 

return f -moveStackPointer; 

I 

HyMovc* GcneraleMovel, 1st(MyMove* mp) 

j 

// Lists all legal moves in a list, starting with a null move; 

// sorts the moves and returns the highest value move on the list 
// Each move is given a ‘'value" reflex: ting its relative merit 
if (tap tkMaxMoves >= endMovePool) 

return 0; // no room lor movdist. should not really happen 
// hut if it does, we just have to hack track 

MyMove m; 

int i, row* col *tnaxRow, maxCol, drow, dcol; 

// create moves 

MyMoveArray ma(kMaxMoves); 

MyWord* w=ntyWordfi; 

ulong beatStrongth=fl; 

for (i=0;i<InumWoi:ds: 1++.W++) 

L 

if (!w->lsAvailable()) continue: 
iilong strengths->Streugtb(); 
if (strength < bsstStrength) continue: 
inaxCol=maxRow=puzzl eSize ■ w * >Lengtb (): 



mf 

■j* r r 

Never a fee 
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// find every legal posilion 

drow^O; 

for 

(row^-puzzleSize/Z: (rov>=0l £ifr(ro w< puzzle Size) :rov*=drow) 

i 

dcal^Qi 

for {eol-puzzleSize/2:(cal>=0) && 

(coKpuzzleS ize) icol+^dcol) 

I 

if ((coK^axCol) && 

(m. IntersectAcrossfw, row. col r puzzle. puzzleSizej^Q)) 

f 

ma.Insert(®): 
bestStrength^strength: 


if ((ravK^axKow) && 

(»■Inte rsectDown(w.row,col.puzzle♦puzzleSize)>°Q)) 

I 

ma.Insert Cm); 

bestStrength^strmigtb: 

i 

if (dcol>”0j dcol = 1 dcolr else dcol~! deal; 
I 

if (drov^^i drow^-1 -draw: else dtov=l drovi 

\ 

I 

ft put a sentinel 0-movc at the start of the niovelist 

mp >Cloor(); 

if copy moves from the moves array into the movriist space 
My Mo ve * nix“mei, Ho v es (); 
for (Int i^O:i<me.HuraHoves():i++; 

*f^p) - *mx++: 

return mp; 

I 

long Execute(MyMove* mp) 

I 

mp >FlaceWord(puzzle): 

PushMove(rap); 
return mp->Pointe(); 

1 

HyHove* UndoUong & points) 

// Undoes the Iasi stacked move, returns this move, or l) if no move found 

t 

HyMove* mp-PopMoveO: 
if {mp^Qj return rap: 
mp->RmnoveWord(puzzle); 
points '» mp->Points(): 
return mp: 

\ 

long CopyMoves&iick (const Words* words,WordPosiLions* 
positions) 

// Scans the muvesUck. eunverts My Moves to positions 
// Returns tlic number of ]x>slLions 
i 

fnr numMoves-O; 
for (HyMovePtr* 

index^TiioveSliick+1 ;iridox<mavt?SLiiekPointer: indox+t) 

I 

MyMove* mp=*index; 

oip->Convert Cwords,positions+mimMuves): 

numHoveell: 

1 

return numMoves; 



Hoard .Solve 

int Board::Solve(const Words* word&.WordPositions* positions) 

I 

WordPositions* pcs=positIons: 
long nmaPositions=0; 
long bestPointsH); 
long start^IickCoimtO: 

Clear (); 

moveStackPointeremoveStack: 

ft Put a sentinri null move at start of move stack 

FushMove(0); 

HyHove* moveLi strove Pool; 
long poxnts=D; 

Kyttove * nextMove-Genera teMoveList(moveList): 

// moveLha to nextMove defines a moveliM which always starts with a O-move 
// and Is processed in order next Move, next Move-1,... until O-movt is found 

if (InextMove) 
return 0; 

for {;:) 

( 

while (nextHove && nextHove-MsVaiidO) 

I 

point &+=Execu r e(n extMnve 5: 

if (points > bestPoints) 

l 

bestPoint s-points: 

cumF o sitions~Co pyHove sflac k t word® * po aitions); 

I 

moveList=ltnextHove: 

long jimnTicks^TiekCourit () start; 

If (nuraTlekn>kH.ixSecnnds*kTicksPerfSeeond) 
break: 

ncx tHove^GencroicMovcIJ st(ranvoLlsr); 

l // end while 

do ( 

MyHo vo* provMove=l]rido( points): 
if (! prcvHove) // stack is completely unwound, exhausted 
break; 

tf try to use the last move: 

nextffove - prevHove-I: 

I while (!nextHove-)1sVaiid()): 

mo vein nr=nextMove; 

while ((tiviveUst>^wovcPo<jl) ith (moveUsT >If>Valld())) 
®oveLisi : 

if (moveList^=movePool) 
break: 

) 

return numPositicms: 

1 

Crossword! I 

short /* rnunberOfWordPositIons */ CrosawordTT ( 

short puzzleSlze, t puzzle has puttelcStac rows and columns 7 

const Words words U, C words to he used to form the puzzle 7 
short numWords. f* numberof words] | available 7 

WordPositions positions [ ] /* placement of words in puzzle 7 
) 1 

If (nujtiWorria < D 0) 
return 0: 

Board B(puzzleSize.words.numWords J: 
long numberOfWordPositions-B.Solve(wQrdfl t positions); 
rnni rn ntitnherOfWordPos i t i om?: 

m 
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A New System Has Arrived. 



Don’t Get Caught 
With Your 
Mac Down! 


#' i « 'mm*' "" '* ' 

Timbuktu Pro 


r“*rr 


No Mac is complete without Timbuktu Pro, 
the premier remote control and file transfer 
software for Mac OS for over ten years. 

No network is complete without the smart 
systems management of netOctopus. 


Both tools are newly rewritten for OS X, 
bringing the power and simplicity of Netopia 
software to the world’s most advanced 
operating system. For deployment, training 
and support of all your Macs (and PCs!) 
Timbuktu and netOctopus are indispensable. 


Are you ready to migrate? We’re ready to take you there. 


Timbuktu Pro 


macosxready.com 

nO 

netOctopus 









COCOA 


By David A. Trevas 


Write a Cocoa Application with 
One Line of Code! 


With Uic advent of Mac OS X, there is whole new way to 
conceive and build Macintosh programs called Cocoa. While 
the Classic and Carbon environments provide a link to the 
single-digit Mac: operating systems, Cocoa is for OS X only 
and, as such, takes maximum advantage of the technical and 
visual improvements of the new system, The use of the 
elegant Objective-C language makes the concepts of object- 
oriented programming very clear. No matter how elegant ihe 
language is, diving too quickly into writing many lines of 
code in an introductory program am discourage many of the 
newcomers to Cocoa, 11 le reader should know how the 
program’s author chose each line of code. It is this thought 
process that the renders need to Learn. I believe dial an 
introductory article should show you around and demonstrate 
how basic tilings work to give you the confidence anti the 
knowledge to go to higher levels. To give you a good 
welcome to Ocx'oa, I have chosen an excellent number of 
lines of code for you to write: one. 1 promise that you’re going 
to lie surprised what you can do with just one line of code! 

This article is intended to introduce you to the structure 
of a Cocoa project, the work How involved in building one, 
and die techniques and terminology of Cocoa programming 
in general. I am assuming nothing alxmt your knowledge of 
programming, but ! am assuming that you have used some 
Macintosh applications and have used buttons, menus, text 
fields and the like. You will need persevenmee-a trial-and- 
error altitude-sinee both of us will lie very lucky if everything 
goes exactly right the first time, even if you follow the 
instructions carefully. You may have to try something a few 
times or even backtrack a little to get things right. 

Create a New Project 

If you don't already have Projectionikler, go to the Apple 
Developer Connection web site and join. “How much is this 
going to set me back?/ you grumble, but the good news is 
that the lowest membership level that can access the Mae OS 


X Developer Tools is ¥REE\ You can become an Online 
Memlxr for zilch and go download Mac: OS X Developer 
Tools including Project Builder and Interface Builder. 

1. Please, open ProjeetBuilder and start a new Cocoa 
Application. 

fm sorry, but I’m not going to lx* able to write “please" 
and Thank yoiT anymore when I ask you to do things. Alas, 
it's the ancient conflict: Barney vs. Word Count. Go to File > 
New Project..., a dialog asking you which kind of project you 
want to use appears. If the little blue triangle, called a 
‘disclosure triangle, 11 next to the word Applications is pointing 
to the right, click on it once to expose the Mil categories. Click 
on Cocoa Application. 

You will then lx prompted to put a name in the upper 
text box, you can use "MyFirst Project" if something more 
brilliant doesn’t come to mind. Notice that you don’t need to 
put an extension {dot-something) because the title is that of a 
folder created by ProjeetBuilder, You may use the Set... 
button to put tills folder in a location other than the one it is 
proposing in the second text box, Ihe -Set... button causes a 
navigation panel u> appear and once you’ve highlighted ihe 
folder into which you want your project folder to go, click on 
the Open burton. Click Finish in the naming dialog. 


David Trevas lives in Houston, Texas with his wife and daughter, two dogs and two Macs. 
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Project Bulld«r File Edit Format Find 


60 © 


D M y F 




O MyFirstProject 


jg 


I© Croups & Filtfi. 


? ^iMyfirstProjea 

> Classes 
vl Other Sources 
|gi} matn.nn 
^ Resources 

> 'J Mam Menu, rub 
t> [£] InfoPlist.strings 

^ 1 Frameworks 

^ Linked Frameworks 
> t) Coco a. fra mework 

> i Other Frameworks 
v iS Products 

MyFirstProject.app 


/. A Ctx:oa Aj plication in Project Builder 


notice, or lit 1 overwhelmed by, is that your simple double- 
click has caused a great many things to happen. Overlaying 
you Project Builder window are now four windows entitled: 
“MainMenu.nib,./, "Cocoa - (something) Palette", 
“MainMenu - MainMentT, and “My Window" You might find 
it a little neater to go to die InterfaceBuilder menu and Wide 
Others to reduce the clutter. 

A little side note: Cocoa is based on work done at 
NeXT which Apple Ixiught in 1997. You will see that 
heritage show through time and again. For instance, a nib 
file is an acronym for NeXT fnicrfuec builder (and I’ll bet 
thai ii is not merely coincidental that a nib is the tip of a 
pen). You will also see the prefix "NS” on all of the objects 
which stands for NeXTStep. 

Disign hie User Interface 

Prom your perspective as one who uses programs, 
you may recognize the things you see in the palette as the 
places you put data or ask for something to happen or see 
the results of the program's Thinking.” Each element is an 
“object" (a concept f will explain later) that lias already 
been w ritten and this frees you from a lot of code*writing. 
"A lot of code-writing” often means “tedium with a big 
probability of making mistakes/’ 


Your projec t then opens up and you’ll see a column 
on the left with five headings each flanked on its left by 
right-pointing disclosure triangles (see Figure 1). The first 
is Classes, it is where the code for the building blocks of 
the project should go. The second heading is Other 
Sources and it contains main.m. which is w here everything 
really happens once the program starts to run. Happily, 
you don't need to touch this file for this project and you 
may get through many more projects before you become 
concerned with the details of its function. The third 
heading. Resources, is the one in which you w-ill be 
working mostly. It contains Main Menu.nib which is the 
basis of the user interface we will be cxeating. The fourth 
heading is Frameworks and under the subheading Linked 
Frameworks resides Cocoa.framework which connects us 
with the years of work done at NeXT and Apple that 
makes our lives easier. Finally, (lie last heading called 
Products contains MyFirstProject.app which is end result of 
our labors, the executable file (Psstl Most normal users 
will see this as a single file, when, in fact it is really a 
package containing several different files, just thought 
you'd like to know?) 

2, Double-click the MalnMenuunib to Open 
InterfaceBuilder, 

Ihe first thing to notice is that by double-clicking a file 
in ProjcciBuilder, you open up InterfaceBuilder. The two are 
actually separate programs (applications) that are 
conveniently aware of one another. The next thing you will 



Figure Z The Views Palette 


Click Lite icons on the toolbar at the top of the “Cocoa - 
(something) Palette” window until you get to the one that 
says “Cocoa - Views Palette” and looks like Figure 2. A liLtlc 
time-out here is necessary to clarify some of this AppKit 
jargon. First, what the heck is AppKit? Cocoa has two main 
aspects: Foundation takes care of things related to the 
fundamentals of programming, while AppKit (short for 
Application Kit) helps you with things pertaining to 
applicatioas such as windows, buttons and menus. Now, 
whafs the deal with views? A* one who works a lot with 
CAD, 1 normally associate views to things tike Front View, 
side View, etc., but that Isn't correct here, l/xasely speaking, 
if you substitute “visible thing" fur "view", you’ll lx* gotxl to 
go at this point. Among these visible tilings are those items 
referred to as user interlace elements, controls or even 


July 2001 • MacTech 


Write a Cocoa Application with One Link of Code! 














































gadgets, 

3* Add user interface elements to “My Window”, 

I lere you will add several of the typical Macintosh user 
interface elements, termed views by interfaceBuilden If you 
complete this entire section, you should end up with 
something like Figure 3 



Figure Window Full of View's (Visible Things). 


Text Fields , Click and hold the mouse over Lite while box 
called die text tax Cor text field). Drag it into the window 
entitled “My Window'” and release it. After you release the 
text field in the window', little bubbles appear around its 
fX.Timeter Grab the middle one on llie right-hand edge and 
pull it toward the other edge of the window and you now 
have a much wider box. 

Go to File>Save (or type Cind-S) to save die nib file. Try 
to get in a habit of saving often - 1 have found 
fiuerfaeeBuilder rt> ta, ehariiably speaking, a hit quirky. 
Better save tiian sorry ! 

Buttons . Drag ihe Button from the palette to My Window, 
Double-click on the word “Button” to edit it. Hits theme of 
double-clicking on words to edit litem is fairly consistent in 
InteifaeeBuilder, 1 put the words “Panic Button" there and 
appreciated the automatic resizing. Did you? 

At lliis point, you have a choice: add more things and 
explore the subtleties of each or get in the Express Lane 
and jump to the next section. For the rest of this section, 
in fact, you can skip down without any long term adverse 
effects, assuming that you come back later and do this 
exercise completely. 

Clieck Boxes . Another easy view (visible thing) is the 
check \sox, which is called “Switch" on the palette. Drag a 
switch from the palette and put it in the window'. Since we re 
talking about checks, ! label the check tax “Duplicate” to 
remind you of the option of having instant copies so you 
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don't have to balance your checkbook in front of me in the 
grocery store line. Thanks for bringing your 23 items to Lhe 
express line, too! Did you remember how to edit the text? 
Tiiafs right, double-dick on the word “Switch.” 

Radio Burtons , Turning it up a notch, we will move on 
to radio buttons and Ixxrause their tahavior is that “one and 
only one” is activated, they only make sense when more than 
one is present. Drag a Radio into the window and notice that 
you get two for the price of one. Now, you say, “Your 
window has three radio buttons, but I only have rwo and if 1 
repeat the step I'll have four buttons, which is still not three, 
so, what [lie heck?!" All, yes, 1 remember the feeling well and 
I mast confess, 1 didn't use “heck”. But the 1 found Alt- 
dragging (a. k. a. Option-dragging) and all was well. Click 
once in the midst of the radio buttons and a box with little 
dots around it appears. I Iold down the Option key and grab 
the tattom center dot and drag it clown-perfectly aligned 
radio buttons materialize like magic. By the way, had you 
selected the lower-right dot and cl nigged down and to die 
right, you’d get rows and columns of radio buttons. 

Radio T Radio 2 and Radio 3 are not exactly names that 
apply For every situation so now you need to edit the words. 
Double-click on “Radio r and sigh as your editing ability 
hasn't returned. Time to call the Inspector! Click once in the 
empty area of “My Window” to undo this last selection. Press 
Cind-SIiilt-1 (i >r go to T< x >1 s> 1 n s j icclc >r, but you will p a )l xt I >1 v 
ta glad to learn the keytaard shortcut) and look at the new 
window dint appears, the title bar tells you what kind of 
object you are inspecting. Push it off to file right a little so you 
have a tatter view of the radio buttons. Click once on the 
buttons and a frame surrounding all three should appear, lhe 
title bar tells you that you are looking at an NSMatrix, that is, 
an array of objects. Double-dick on Radio I again and now 
the Inspector title bar says that your are looking at an 
NSBuitonCell. Double-click now on the button tell and you 
can edit it, I called them "AM”, "FM” and “SW" for short wave 
since these could be buttons on a radio. If you double-clicked 
on the Matrix and Keanu Reeves and Inwrence Fishburnc 
popped out and started kung-lu fighting, you clicked the 
wrong Matrix. The difference between an N SB Litton and 
NSBuitonCell is not important for this project, but fed free to 
poke around in the AppKit documentation to find out more. 
Sony, no extra credit. 

Po p-1 )p Mentis . These are straightforward, but things 
get a little Lriekier for pul I-downs. Drag a pop-up menu 
from the palette to “My Window”. Double-click over the 
phrase, “Item l", and you will notice that three items 
appear. What if you want more? Keep in mind that this is a 
menu and what you will learn in the next section about 
menus will apply. Double-click again over an item’s words 
to be able to edit them. I called my items, “Corn”, “Toast" 
and “Weasel" lbr things that go “pop.” 

Pull-Down Menus . The way I found to create a 


MacTecii • July 2001 


24 
























One incredibly successful project manager. 



C FastTracH 


What does this guy know about software development that you don't? He knows that 
with FastTrack Schedule 7,0 he'll shave hours off the time it takes to organize, track and 
manage the details of all his development projects. And hts eye-popping schedules are 
sure to turn heads and get results. 

Whether the project on tap is coding the next killer app or putting a fresh coat of paint 
on a client's website, FastTrack Schedule's three powerful views display your information 
the way you want—as a schedule, a calendar, or as a resource graph that tracks the 
people, equipment, and materials crucial to project success. 

And with our new compatible Palm 05 version, you can sync schedules between your 
desktop and handheld. So even when you're on the run, your schedules are right at your 
fingertips. FastTrack Schedule also includes FastSteps™ intra-application scripting, full 
support for AppleScript, and is available in a compatible Windows version. For a free demo 
version or to order, call us today at 800,450.1983 or visit www.aecsoft.com. 

Easily the best in Project Scheduling! 


AEC 

SOFTWARE 

FastTrack 

vif'li Scfisiluiol 

***** 





m 




* * 4 r ■ 














pull-down menu is to sum its Life as a pop-up. Again, 
drag a pop-up menu from die palette m “My Window”* 
Double-click over the phrase, 44 Item 1”, and double¬ 
click it again to be able to edit it. In a pull-down menu, 
the first item is not a choice but the permanent title of 
the menu, just like a menu title from the menu liar. I’m 
calling this menu “Pulling Forces* and hitting Return. 
Call up the Inspector (Cmd-Shifl-I or 
TooIsMnspector.,,) and click once anywhere in the 
empty space of the window and return to the pop-up 
you want to change and click it. The Inspector's title 
bar should read “NSPopUpBuuon Inspector* and if it is 
not already showing, choose “Attributes” from the pop¬ 
up just below the title. Simply choose the PullDown 
radio button to do the switch- Now, when you double- 
click over “Pulling Forces”, you will see Items 2 and 3 
in a box slightly below the button itself. Double-click 
on Item 2 and call it "Gravity* and change Item 3 to 
“Magnetism”. 

If you've done this kind of work before, you will 
notice some things missing in the Views Palette. That's 
why there is a More Views Palette (see Figure 4). 
From this palette, we will take two elements: a slider 
and a combo box. 



Figure 4. The More Views Palette. 

Sliders . While you see four different sliders, they 
are all the same except that their attributes are set 
differently. Choose the one you like best and drag ii on 
to “My Window," You can play with the attributes if 
you like. Of course, how am 1 going to stop you if I 
didn't want you to play with them? 

Combo Boxes . Finally, drag a combo box front the 
More Views palette into “My Window." It is a somewhat 
a combination of a text box and a pop-up menu. 


Wider a Cocoa Appucatiok with One Line of Com:! 



Figure 5. NSComboBox Inspector. 

To put in your items, call up the Inspector (Cmd- 
Shift-I, or Tools>lnspector, if you insist) and choose 
“Attributes" if you are not there already. The entry box 
is that little one at the bottom (as seen in Figure 5). 
ClJck in that box and type the text you want and hit 
Return. Repeat as often as you wish. I entered “Peanut 
Butter & Jelly” , "Macaroni ik Cheese”, and “Soup & 
Salad/' J also changed the “Number of visible items 1 ' to 
three. 

Feature: The Macintosh Human Interlace 
Guidelines, 

We Ye plopping the views (visible things) somewhat 
chaotically in the window and well be asking some of 
ihem to behave in ways that are not normal in Mac 
programs. This is O.K. since we Ye just throwing 
together a little intro here. However, if you plan ro 
create programs for wider consumption, there is some 
must-read material at the Apple web site that you just, 
uh, must read. If you love Macs, til bet that one big 
reason you do is the Macintosh Human Interface 
Guidelines. This book details the proper usage and 
placement of each element of the user interface and the 
fundamental Mac philosophy with regard to the 
interaction between person and computer. Since these 
guidelines have been widely available for years, 
software developers have been able to c reate programs 
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with .such consistent interfaces that learning to use 
them is much easier than on other platforms. So go 
download Macintosh Human Interface Guidelines and 
don't forget Mac OS 8 Human Interface Guidelines and 
Aqua Human Interface Guidelines that add guidelines 
for elements that were introduced in Mac OS 8 and Mac 
OS X, respectively. 

4. Add a new menu title and items to that new 
menu. 

Go to the Menus Palette. You’ll notice (hat pre¬ 
defined menus for some of the most widely used 
menus are there. Then, there are three other items you 
use for creating your own menus and modifying them 
and the pro-defined ones: Submenu, Item and an 
apparently blank one. 



Figure 6 . I he Menu Palette. 


“Submenu" means “menu title or menu item with lower 
level items" 

“Item" is a menu item that doesn't have sub-items. Items 
are the only tilings on menus that internet with the rest of the 
project. 

The blank one is a divider (not a uniter), also known as 
a separator. They simply provide a space so that you can 
group menu items into logical and visually appealing units. 

When you complete this section your menus should 
appear like tl ic ones in Figure 7. 
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Figure 7 I he Menu System of the Project, 


Separators . The easiest thing to do is to place a 
separator. First, look at I he window entitled “Main 
Menu - Main Menu" which might not sound like a 
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for the List Manager ? 

We lied, it is much more ! 
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The Keyspmi Digital Media Remote is a powerful infrared remote 
which allows you to control multimedia applications on your 
computer in the same convenient way that you now control your 
home TV. Great for PowerPoint, QuickTime, DVD players, 
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weird name if you live on Bora Bora, eat couscous or 
have beri beri. It represents the menu system of your 
project. Click once on the Edit menu of "Main Menu - 
Main Menu” to see a pre-wrillcn menu that has some 
of your trusty old friends like Cut and Paste on it. 
Meanwhile, back at the palettes, dick on the menu 
palette icon at the far left of the toolbar. Click on the 
empty blue box at the bottom and drag it toward the 
edit menu. Notice that you are dragging a blue 
rectangle attached to the arrow representing the 
position of your mouse. It seems that Interface Builder 
considers the tip of the arrow as your intention when 
moving something that takes up a lot of real estate. 
Move the tip of the arrow, therefore, to a point below 
the lower half of the words Select All and let go. A 
space should open up just below the Select All item. If 
it doesn’t, hit the Delete key and try again. 

Items . Once you’ve done this, you can put items in 
your own new section of the Edit menu. This time drag 
an “Item” from the paleue to the Edit menu and drop 
it below the separator To edit the text, we do what? 
Double-click on the wortl “Item” and type “Wipe Out” 
as if you wanted a command to nuke your current 
work so you can start over again. 

If you are cruising through this exercise in the 
express lane, you can jump to the next step. 

Command-Key Equivalents . Once you have 
become familiar with a program and lire of reaching 
for the menu bar for doing routine operations, you 
learn the command-key equivalents, also known as 
keyboard shortcuts, The key with the Apple and the 
propeller (or clover or flower) on it is called the 
Command Key (abbreviated Cmd in documents that 
don't have a font that has the symbol.) You know the 
typical command-key equivalents: Cmd-N for New..., 
Cmd I 1 for Print..., Cmd-X for Cut, CmcbC for Copy, 
and so forth. To create a command-key equivalent for 
“Wipe Out”, move your mouse to the Wipe Out item in 
the Edit menu and then to the far right side of that 
item, directly under Cmd-X and Cmd-C. Double click 
and a little white outline rectangle that might hold one 
character appears. Here is where you type the keys 
that go with Command Key symbol (Ye,, don’t use the 
Command Key) which usually is a letter. Type “F and 
nothing happens, why? Because, if you look at the File 
menu, you will see that Close is already assigned to 
Cmd-W. Interface Builder automatically makes sure that 
you do not reuse keys or key combinations (of course, 
it would be nice to get a warning and then prompted 
to try something else.) Repeat the step to get the 
outline rectangle to appear and this lime hold down 
the Shift key anti type “W’\ You see that the characters 
Shift (an upward-pointing arrow), Cmd, W to the right 
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of “Wipe OuC are now the command key equivalent. 
Now you are ready to make your own menu. 

Submenus . Drag a Submenu from the palette to the 
Main Menu bar and place your cursor arrow between 
Edit and Window. Double-click the newly placed text 
and type in “Dinner". Click once on Dinner and 
underneath a single Item appears. Double-click on it 
and call it “Chicken.” Now comes the most excruciating 
part of the project (at least it was for me-you may 
benefit from my ordeal.) To make the first command- 
key equivalent in a menu Lakes a keen eye and a 
steady hand. Ever so gently, place the tip of your 
cursor on the right-hand edge of the “n" of the word 
“Chicken,” and double-click. If you got that rectangular 
outline to pop up on the first try, you definitely 
benefited from my tribulation. Use “K” for the 
keyboard shortcut. Is it just me, or doesn’t it seem that 
the ability to create a keyboard shortcut should be 
available in the NS Menu Item Inspector window? 

Now, for the more familiar use of submenu: a 
menu item with a right-pointing triangle that guides 
you to more choices. Drag a Submenu to the spot just 
below “Chicken" in the Dinner menu. Double-click it 
and call it "Pish." Click once on “Fish” to see the item 
and rename it 'Tuna." Now, with you newly-found skill 
at placing the first keyboard shortcut on a menu, 
double-click at the right edge of the "a 11 in “Tuna”. In 
that outline, hold down the Option key and type “T” 
and you will see that the keyboard shortcut for Tuna is 
weird symbol for Option, Cmd, T, (If any of you knows 
where that weird symbol for Option comes from, 
please tell me.) 

Hopefully, you are now in tuna with the menu 
system and are not floundering about. If you are up to 
it, add an Item below Puna called “Flounder” and set 
its keyboard shortcut to Option-F (of course, the Cmd 
adds itself automatically.) And why not just one more 
for the halibut? Add an item and call it “Halibut" and 
set its shortcut to Option-H. 

Make* a New Object in InterfaceBuildlk. 
Feature: Objective C and Object-Oriented 
Programming. 

Before we can continue, we need to discuss a few 
concepts and terms. Objective-C is a language that 
extends the C language by making the object the 
central unit of programming. It is the original language 
of Cocoa and its predecessors, although current Cocoa 
programmers have the option to do their work in Java. 
If you know C, you should he able to pick il up 
quickly by reading Object-Oriented Programming and 
the Objective-C language which available freely from 
the Apple web sites If you don't know C, you can learn 
ii later and just follow the code-writing parts as 
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written. As one who has struggled several times to 
really “get* C++, 1 found that Objecrive-C provided a 
much better way to understand object-oriented 
concepts and yielded code that was much more 
readable (after I got used to the square brackets and 
the colons). 

Cocoa applications are generally conceived as a 
network of objects. You can think of objects as people. 
Different objects know different facts (data) and 
possess different skills (methods). Like people, they 
can communicate with one another. Using mess ages, 
one object can ask another for information or to do 
something. They can also talk to themselves, but that 
is not a sign of mental illness for objects. 

The descriptions of an object’s knowledge and 
skills is contained in its class , also known as a factory 
in Objective-C An object is an instance of a class (or 
the product created by a factory.) 

A class can have children and pass along its data 
and methods to them. A child class can add more data 
and methods and alter the methods ii inherited. The 
child class’ methods can deviate from its parent’s 
completely, slightly or not at all. 

Often one finds a class that somewhat does what 
one wants and uses that as a basis to create an class 
that does exactly what one wants. Almost every class 
in a CocOa project inherits (either directly or after a 
few generations) from a fundamental class called 
NSOhject. NSGbjeci handles things like object 
identification and memory management, so a great 
deal of knowledge and courage are required if you 
want to avoid it. 

In this way of writing programs, your concept of 
data needs to expand from what you may have learned 
from earlier languages. As before, there is some data 
that lives within the object. For example, a Rectangle 
object may have data members called “Height” and 
“Width*, In Ohjective-C, however, a common piece of 
data is just the address (or location) of another object. 
We say that this piece of tlaia “points to” the other 
object. To return to the metaphor of people, it brings 
to mind the saying, “it’s not what you know, it’s who 
you know,” Witness the ongoing value people put on 
their address storage systems from little black books to 
Rolodexes to organizers to Palm Pilots and you will see 
why there is power not only in knowing things and 
having skills, but also in knowing where to find others 
who have knowledge and skills that you don't. 

5. Create a subclass of NSObfect as the Application 
Controller. 

We're going to need an object that acts as a traffic cop lo 
direct all of the input that comes from our burtons, sliders, etc. 
and send some kind of output to the text field. We cull tills 
kind of object a “controller.” We aren’t yet aware of a good 


starting jx>inl for a controller, so we create the blueprint (or 
class) of a controller that inherits from NSOhject. Another way 
to say it is that the controller should Iv a subclass of 
NSOhject. 


Inter facc&yiUtef Fite EdH Classes Format Layout 


Classes Tab 


Classes Menu 



Figure H. MairtMcmiiMh Window with Classes Tab Selected. 


In the MainMenu.nib window, dick on the tab called 
Classes and your screen should show you something very 
much like Figure 8. Scroll to the very top and find 
NSOhject. Click the NSGbjeci once and go to the Classes 
menu located on InterfaceBudder’s menu bar at the top 
of the screen. Select Subclass and a new class called 
“MyObjecC appears, ready to be edited. Change the 
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name to “MyContraller." (Using names beginning with 
“my" is an old cliche for introductory programming 
exercises. Ii is supposed to indicate the separation of the 
words that you must use exactly as specified by the 
language from the those with which you have some 
freedom. You may indulge my penchant for corniness or 
call this object something else if you want.) 

(>. Add an outlet to the text Held. 

An outlet can be thought of as the place where dura goes 
when it is ready to leave the controller. To create one, dick 
on MyController if it is not already highlighted. Go to the 
Classes menu at the top of the screen and choose Add Outlet. 
Call the outlet "theTextField.” 

Notice the two icons in the right-hand column. The first 
one with the two vertical lines is supposed to remind you of 
an electrical outlet. Since you added the outlet, the numlXT 
1 appears just to the outlet symbol’s left. And, by the way, 
this is one of those pieces of data that is only the location, 
or address, of another object. In an upcoming step, you will 
lx- tell this piece of data die object for which you want to 
store the address. 

7- Add actions for each control and menu turn 

The other symbol next to die outlet is a small gray circle 
with crosshairs anti it is tailed a target. These are to what the 
buttons, sliders, menu items and so forth will be shooting 
their requests. Instead of feeing the address of an object like 
the outlet is, an action occurs when the target is hit. An action 
Ls a special type of method. 

Highlight MyController again if it isn't still in locus. Go 
Ixtck to the Classes menu again and tills time chouse Add 
Action. Start typing your action name and it will replace the 
generic* myActfon: that appeared. Make sure that you end each 
name with a colon. 

I lere are the ones I used: 

pushPanicButton: 
checkDuplicates; 
radioAM: 
redloFM: 
rod SoSWr 
popCorn: 
popCork: 
popWeasel: 
pul J-Graviry ^ 
pul l Magneti snt : 
siideHeadFirst: 
eomboLimch: 
menuKditWipeOut: 
ittenuDiimerCli i rkon : 
menuDirmerTuno: 
menuBinaerFlounder: 
menuDinnerHalibut r 

Those of you in the express lane need only create the 
push Pan icButton: and menuEditWipeOut; actions. 
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8. Instantiate the new controller. 

What you T ve done in the prevkxis three steps is create a 
class (or factory) for a controller much like an architect 
creates a blueprint for a house. Can you live in a blueprint? 
No, you have to build a house according to that blueprint to 
have something to inhabit. Similarly, you have to create an 
instance of the controller class in order to use it in your 
program. The verb. Instantiate", was invented in 1949, 
according to my dictionary, to compress the phrase* “create an 
instance" into a single word. 

Now' that the concept is clear in your mind, go to the 
Classes menu and choose Instantiate. Click on the Instances 
tab of the MainMenu.nib window and you’ll sec that there's 
good news and there s bad news (see Figure 9> 



Figure 9. Ihe MainMeuu.nib Window 
with Instances Tab Selected. 

The good news Ls now you see a cube labeled 
“MyController in the window (provided you are in icon 
view. If you are in list view, kx>k at the far right side of die 
window at the top of the scrolling area, and you will see a 
small square with squares in it. That is the icon-view button. 
'Ihe square Ixrlow it with the horizontal lines will get you 
Ixtck to list view. Now you’re marveling at tile cube you've 
created and are wondering what could lie had about this. In 
informal discussions, we often use tlx* ten ns “class" and 
“object" interchangeably, when, in fact, an object is an 
instance of a class. To return to the metaphor of people, a 
class b like a job description and an object is like the living, 
breathing person who has the job. The MyController you 
have built from steps 5-7 is a class and the one you just 
instantiated hem is an object of that class, The convention in 
Object ive-C is to capitalize the first letter of a class, and to 
have an object start with a lowercase letter, Double click on 
the words “MyControlled 1 and rename it "itsMyController/’ 
Now, your joy can be unbridled! 

Connect the Covikoluer to the Views (Visible 
Things). 

Now that tile cube representing the controller appears in 
the MainMenu.nib window, you have a visual representation 
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of all of the objects in your project. Perhaps you think it might 
he pretty cool if you could connect them all up with some 
fxjinLs and dicks of the mouse. Well, you can! 'Hie basic 
principle is that you click on Lhc “from* 1 item, hold down the 
Control key, drag to the “to* item and let go. 

9- Connect die controller to the text field. 

For an outlet, you want data to How from the controller 
to the outlet object. Click once on the icon called 
“itsMyController* to select iu Now. hold down the Control key 
and drag the L-shaped line to the text field. This is shown in 
Figure 10 . A dialog box opens up an allows you to select an 
outlet Claxxse theTexlField and then click on Connect 
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Figure IQ. Making the Connection 


10* Connect the controls and nienu Items to the 
controller and select the right actions. 

Fortunately, connecting views (visible things) to the 
controller works the same way. This time the request for 
action comes from the view (visible thing) and goes to the 
controller Select, say, a button, then Control-drag to the 
u itsMyController icon. The difference here Ls that you are 
now prompted for an action. This means choosing die 
radio buttons individually (as NSButtonCells) to connect 
each one with the right target. Likewise with the pop-up 
and pull-down menus, except it is NSMenu Items you must 
connect individually. 

In the dialog dial pops up after you’ve made a 
graphical connection, the actions you may connect to are 
listed in the right-hand column. If not, click on target in the 
left-hand column. 

Menu items behave exactly the same way, so all you 
have to do is Control-drag from the menu item to the 
controller in order to connect the menu item with the action 
it should do. 


Generate the Code and Write the One Line. 


11. Create die skeleton of the code for the controller. 

When you've completed this work, a little treat appears. 
Since you’ve been doing repetitive connections for a while, 
you probably are not looking forward to writing code for all 
of those actions. The gtxxl news is: you don’t have to. Simply 
dick once on the "MyController" icon and go to 
Classes>Create files... anti navigate to the folder of this 
project. Ba-da-boom, ba-da-bing! Hie basic interface file 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that's where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- Vie w-Controiier 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code” 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B»0*W»li»R»S 

Development 

I’.O. Box 929, Grantham, Nit 03753 • (603) 863-0945 • FAX 863-3857 
bowersdev@aol.com • http://tncmbers.aol.com/bowersdev 
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(ending in .h and called a I leader file in C) and its 
implementation file (ending in an, the Objeetive-C source file 
ending analogous to x in C and cpp in C++) appear in 
i nagieal! y Prc >jctt 13u i icier. 

You can now save your nib file and quit Interface Builder 
now that your interface is, uh, built* Click once on the 
ProjeciBiiilder icon in the Dock to bring it out of hiding. The 
version of ProjectBuilder/InterfiiceBuilder that I am currently 
using puts the MyController.m and MyControllerh files in 
strange places. Please put them in the top folder, the Classes 
folder. Thank you. 

The concept of separate files for Interface and 
implementation makes a lot more sense as projects gel bigger 
arid bigger. It is a Ix+Ler idea, therefore, to get you into gcxxl 
habits when you i starting off small than trying to force change 
on you after you’ve developed ixtcl ones anti are entangled 
in a huge mess. Tiie interface Ls the place wliere you 
introduce the data (variables, memliers) and show whit 
methods (functions, subroutines) are available to the object. 
The implementation is where you put the mop, the detailed 
instructions of how to actually do the tilings you promise in 
the interface. 

Here is the axle generated for you and placed in 
MyControllerh. Alter you examine iL. I will explain some of the 
features of this code that are unique to it and not Objective- 
C concepts you can get by reading Chapter 3 of the lxx>k 
mentioned alx>ve. 


listing 1: The interface of the controller class, 

#import <Cocoa/Cocoa.h> 

Winterface MyCantroller : NSObject 
i 

TBOyrlct irf thcToxtFleld: 

I 

(lBAction}ctiuckDuplicaLcs: (id)sender: 
(LBAetiordeomboLumch: (id)sender: 

- (IliAction) menuDinnerChicken: {1 d) sender : 

- (TBAction)menuDinnerFlounde r:(id)sender: 

- (IBActionJmemiDinnerHalibut:(id)sender: 

- (TBAction)menuDinnerTnna:(id)sender: 
(TBArtton)-memiKd I rWI poOnt : (Id)sender; 

(TBAc i ion)popCorn:(id)sender : 

(T BAclIon)popToas L:(Id)sender; 

(IBActioii)popWeasel:(id)sender; 

- (IBAction)puiiGravlty:(id)sender: 

- (IBAction)pullMagnetism:(id)sender: 

- (IBAction)pushFanicButton:(id)sender; 

(TBAct lon) rs rl 1 oAM: (Id) fiend e r : 

- (TBAct ion) rnd t oFM i (td)sender; 

(TBAction)rodloSW:(Id)sender; 

(IBAction) slIdellead+irsL : (id)sender: 

@end 


“IBOutlet" means nothing, it is just there to remind you 
of Lhe purpose of the object there. You may be offended by 
this apparent waste of space, but rememlx^r, code is not just 
a communication fbetween you and the machine, it is a record 
of your intended goals for others to read (and one of them 
can lx: you months or years later.) 

“IB Action” meaas "void" which, in the case of a method, 
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states that it returns no value. 

“sender” refers to the view (visible thing) that Ls causing 
the action* As you progress, you may lx* interested in 
knowing the value to which the slider is pointing, for 
instance* and then you will make use of the sender object. 

Here h a question you may ask; G.K.* wise guy* you 
said that each user interface element was an object, but I 
only see one, “MyCont roller”* where are the others? Good 
question, although l could do without the attitude, The views 
(visible things) are stored in the nib file — the construction 
and functional details of “My Window” and everything in it 
is kepi in the nib file. To keep you on the edge of your .seat* 
notice that the controller is different from the view's (visible 
things), H minimum? 

12. Add tills code to any of the actions. 

Go to the MyControllerm file and place your cursor 
between the curly braces of the first method* 
checkDuplicates(). 

Now, the moment you have all Ixxti waiting for (or 
dreading): Hem is the one line of code you need to make this 
project do something. 

[theText-Fiald setStringValue:@*'You*ve done this 
act ton.**] : 

[ low did l come up with that? When I pul the text field 
in "My Window” is noticed that its Inspector indicated that ii 
was an NSTexlField. I went to the Application Kit Table of 
Contents page (AppKitTOC.litrril) which came with the 
Developer Tools* but is also at Apple's web site, I clicked on 
NSTexlField and scanned the available methods and did not 
find a suitable one. I reniemlxTed that classes inherit the 
methods of their parents. At the top of the page, I saw ihat 
NSTexlField is a child of NSControl (Lite lineage is expressed 
with the closest ancestor being the leftmost in the chain.) On 
the page tor NSControl I found rhe setStnngValue: method 
which was exactly what I needed. 

listing 2. The top lines of an dirty version of the 
implementation of the controller class. 

itimpQi L "MyCon t ro 11 cr . h' 4 

@ i mp 1 eme n t a t i on My Co nt rc 11 e r 

- (IBActiortJchockDuplicates: (Id)sender 
I 

[rbeTecxtField petStringVmlue:@**Ycu*ve done zhis 
action.**] i 
) 

Here* the square brackets indicate that enclosed text is a 
“message” where one object tells another to do something. 

Tile message hits two major paits; the first is the receiver 
(in this case, theTextField ). U Is the object that receives the 
request from the bossy controller 


Write a Cocoa Application with Onk Link of Cook! 


The second part is the method {setstring Value:) and it 
represents the method or function lor ihe receiver to perform* 
The methcxl must be one that the receiver can do or you II 
get an error. 

The colon is significant because the numlxjr of colons 
in a methcxl definition indicates liow f many parameters, or 
arguments* that the method requires* I lere, the one colon 
means tliat one parameter Is required for this method and it 
just so happens that it needs to lx* an NSString. A string is a 
group of letters* numbers and oLher characters. However, you 
want to make sure that the compiler (the program ihaL 
translates the axle you written as text ihaL someone could 
read into instructions that a computer can read) does not 
think your string is part of a computer language or a name of 
a class* variable, method etc. In C f one simply puls a string 
between double quotes, An NSString offers many advantages 
and Is most easily created by putting an at-sign (“@0 before 
the siring you enclose in double quotes. 

Don't forget the semi-colon after the message as that 
signifies U lat die “line" of code is complete. A "line” of code 
in any of the C-based languages can Span several lines of 
screen (or paper) and often improves clarity. For that 
capability, we accept the responsibility of explicitly 
terminating every line of code with a .semi colon. If you are 
new to programming* you will probably make this error 
repeatedly, but fortunately* most compilers these days are 
smart enough to show* you where you may have forgotten to 
put a semi-colon. 

Feature: The Model-View-Controller Scheme. 

There Ls a methcxl of creating large projects by creating 
three different types of objects. Tills Ixang a small project 
you’ve only worked with two out of three (and Meat Loaf 
fans would say that ain't bad.) You have used the views 
(visible things) provided by InlerfaeeBuiklcr and dealt with 
litem using the controller you created. In the controller, you 
wrote the single line of code to take the input and generate 
an output, but you cun imagine that you may want to send 
the input to ail object tliat could some fancy stuff with it and 
gives you hack some amazing result that the controller 
could pass back into the views. These objects tliat work file 
really interesting stuff on the data are allied mo dels . 
Creating a project in this manner observes the model-view- 
controller scheme. 

There are many benefits to doing your work this way. 
The models and views* particularly custom views you may 
develop later tin* am reusable in various projects. It makes a 
large application easier to maintain by allowing tweaking of 
models or views without having to worry about the other - 
file controller or controllers provide the separation to ensure 
this. This means* of course* that the controllers are very 
specialized for each project and are generally not reusable. 

Some projects may get a performance boost if you 
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combine the functionality of con toilers with either models or 
views, but that probably won't l>e a burning issue for most of 
us. llie motiel-view-controller method is an excellent way to 
structure a project, but 1 wish it were called model-coiUioIler- 
vicw to emphasize the separation of die model and view by 
die controller. 

13- Copy and paste tJiis line to all of the other actions. 

Highlight the message you just wrote and choose 
Edit>Copy (Cmd-C). Paste (Cmd-V) this line txiween all of 
the action methods in die implementation file, 
My Controller rn. Pasting copies of this function does not really 
count as writing, so the title is still truthful, right? 

14. Allow user to modify die string to be more useful. 

1 also didn't say you wouldn’t have to modify dial 
single line. As we discussed alxm_\ a string is a group of 
characters dial were not part of a programming language. 
If you are modifying text that is not as restricted as actual 
code, this activity shouldn't count as writing code. You 
don't really have to do this, but your application will be 
awfully boring if every time you do something, the generic 
message always shows up. 

Listing 3: The final version of the implementation of 
die controller class. 

^import "MyController,h" 


^implementation MyController 

{TBAction)checkDuplicates: (id)sender 

I 

[thaTextField setStringValiie:®"YcHi those duplicate checks."J ; 
I 

- (IBAction)comb oLunc h: (id)sends r 
I 

\theTextField setStringVal,ue:@"YQU have chosea your lunch 
combo."1: 

I 

- (U5Action)menuIJirirterChlckeni ( Id) sender 
f 

ItheTextFieid setStrinEValue:^' , ¥ou selected chicken for 
dimer. "1: 

\ 

(IBAct loti)menuDinnerFlounder: (id)sender 

t 

[theTextField selStringValue:@"You selected flounder for 
dinner."J; 

\ 

(IBAction)menuDinne rHalibut:(idjsend er 

EtheToxtField setStrin&Value;^”Yoii selected halibut for 
dinner."]: 

I 

- {IBAction)raenuDinnerTuna: lid)sendee 

I 

[theTextfield £GtStringValue:@"You selected tuna for 
dinner,’"]; 

I 

- [IBAct ion JmenuEditWipeOuLT(id)sender 

I 

ftheTextField setStringV&luerff'You want to wipe everything 
out? w l; 
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(IBActiun)popCo rn t(id)sender 

I 

ftheTextField setStxiagValu^iTYciu have popped torn.”]; 

I 

(TBAr tion)po pToast•{id)sende t 

I 

ItheTexLField setStringVal up;#"Y ou have popped toast."]: 

1 

- (IBAction)popWea s e1:(id}sende t 

I 

ftheTextField, set£triji£Value;#"Pop goes the weasel,"]: 

I 

(iBAction)pullGtav1ty:{id)sender 

J 

[theTextField setSldngVatue;#"GravHy pulls all,"]; 

) 

- (IRActionJpullMagnetism;(id)sender 

I 

ftheTextField setStringValua:#" Magnet ism pulls iron."]: 

) 

(IBActlgn) pushFanlcBuLLoti: (id)sender 
E 

ftheTextField setStringVaiue:# M Ca!ra down, all will be 
fine."]: 

J 

(iBAc tIon)rad1oAM:(id)sender 

f 

ftheTextField setStringValueitTAM radio traffic, weather 
and news"]; 

I 

(TBActi an) radioFM: (id) sender 

f 

L theText Field setStringValue:# M FM radio - all hits, 
all day, all night."]; 
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(TBAction)radioSW;(id)sender 
I 

[theTextField setStringValue :@ fh Short Wave - Ham it upPj : 

1 

- (IBAction)s1ideHeadFirst:(id)sender 
[ 

[thcTextPield setstringValur:g”Safc at home we win!"]: 


#end 


Bring hie Project to Lite 


15, Build and run it 

Simply go to the Build Menu and select “Build and Run.” 
If errors occur, double-check the code you wrote in 
MyController.m to ensure that the airly braces, the square 
brackets and Lhe quotes all have matches. Make sure that 
each string in quotes lias an at-sign in front of it and that there 
Is a semi-colon after each dosing square bracket 

If everything goes well, on the other hand, you may 
be disappointed that nothing has apparently happened 
except that the menu bar reflects your changes. Just go to 
Lhe Window menu and select "Bring All to Front”. The 
reason you needed to do this manually is because I did not 
discuss the lines of code you would need to bring the 
window to the front on startup. You should now see you 
creation in all of its glory! 

Click the buttons, slide the slider, choose each item in the 
pop-up and pull-down menus, click on your menu entries 
and try Lite keylx>ard shortcuts. Did they all work as planned? 
If so, congratulations, otherwise you may notice things you 
forgot to connect or connected in correctly, 

When you art: finished, you can click Cmd-Q or go to 
MyFirstProject>Quit to quit your application. 

Now, was that fun or what?! 

Conclusion 

if you are reading tills, you have covered a lot of ground 
in a short time and you should lie proud of yourself. You've 
learned how to use Project Builder and InterfaceBuilder and 
were introduced to objects and classes, Objective-C, 
inheritance, messages, views (visible things), menu making, 
larget/action, outlets, connections lx;Lween objects, model 
view-controller, human interface guidelines, AppKit and 
Foundation (which make up the Cocoa framework), 
methods, receivers, interface and implementation, inspectors, 
keyboard shortcuts, instantiating and subclassing (1 hope I 
haven't missed anyone.) By touching on these topics, I hope 
you got a good big picture 11 view of what Cocoa involves 
and are encouraged to pursue learning of this amazing way 
to mitking our Macs even more useful, friendly and fun. Best 
of luck and thanks for your time. HQ 
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Internationalization and 
Localization 

(Translation: Why you should you read this article.) 


I 'm not going to talk alxiut localization or why you should have 
your application translated to French. Instead, I’m going to talk 
about something we both can relate to: money. 

In 2000, almost half of Apple's revenues came from outside the 
US. So, if your application supports only U.S* English, you may be 
missing out on half of the market (and revenue) for your product* 
That’s the bad news* 

1 fere’s the good news: With Mac OS X, Apple introduced new 
technologies to help you bring your application to international 

markets quickly and easily. Head 
on for more information and 
remember: If you don’t get your 
product to foreign markets, you 
can always count on your com¬ 
petitors to do so. 

Mac OS X: An 
International OS 

With the introduction of Mae 
OS X T Apple redefined what 
a truly international plat¬ 
form should be. Take a look 
at a clean install of LMae OS 
X and you'll notice support 
for many languages—seven 
to be exact. At its introduction, Mac OS 
X was released in seven languages: English Japanese, French, 
German, Italian, Spanish, and Dutch. A new' version of Mac OS X 
was released during the 2001 Worldwide Developers Conference 
that contains support for Korean, simplified and traditional 
Chinese (as well as the rest of the European languages.) 

Mac OS X streamlines internationalization* From a new 
International pane in the System Preferences, to new technologies 
dial help developers take advantage of Unicode™, Mac OS X stream¬ 
lines internationalization. A new delivery mechanism enables devel¬ 


opers to ship several languages in one bundle. In addition, Mac 
OS X includes new technologies that handle Unicode and complex 
scripts. Both will be discussed in more detail here. These advents 
will undoubtedly make Mac OS X Ijc international OS." 

Internationalization Made Easy 
(Translation: Why you should bundle your 
application.) 

Mac OS X makes it easy to internationalize software and it does so in 
such a way that a single binary can support localizations for multiple 
languages and regional dialects* li also lets software developers 
dynamically add localized resources for new* languages or regions. 

In Mac OS X, most software comes in the form of a bundle, of which 
an application package is just one type* 

A bundle is an opaque directory in the file system that contains 
one or more executables and the resources that go w ith those exe¬ 
cutables. One of the primary benefits of bundles is the infrastructure 
they provide for localizing software. Localized resources such as 
image and string Files, as well as Mac OS 9-style resources (rscs), 
can be put in bundle subdirectories whose names reflect a particular 
language or regional dialect (for example, Canadian French). A 
properly constructed Mae OS X application {or plug-in or shared 
library) does not hardwire paths to the resource files in these direc¬ 
tories. Instead, when the application needs a resource, it uses a spe¬ 
cial system routine to obtain the localization that best matches the 
user's language preferences. (Please download “Inside Mac OS X: 
System Overview” if you'd like more information on Application 
Packaging and Bundles*). Go to: 
httpd/devebpenapple. comfmacosxf 

The new International pane in the System Preferences intro¬ 
duces users to a new f paradigm in .selection. In the following exam¬ 
ple (see fig, la), youll see preferences regarding language order¬ 
ing. The preferences were changed to have Japanese as the First 
language, French second, and English third* Next time the user 
logs in, the Finder will have it*s UI in Japanese, (Apple introduced 
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Fig. la - This is the International pane 
from the System Preferences. 
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Fig. 2a - An example of what is inside a 
bundle. {TextEdit in this case.) 
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Fig. 3a - Localized languages installed 
as shown in the “Show Info 11 panel. 


“Show Info” pane) (CMD+f) (% 


a new font called Hiragino 
w r irh Mac OS X to display 
Japanese text. It looks gor¬ 
geous on the screen and in 
print. ) The ordering of the lan¬ 
guages means that if a user has 
an application that has been 
localized in French and 
English, the Finder will launch 
the application and load the 
resources in the French folder. 
From a developer's point of 
view, if you bundle your appli¬ 
cation and have the localized 
resources in the appropriate 
folders, then you don't have 10 
do anything special in order 
to generate this behavior The 
System will load the appropri¬ 
ate resources corresponding to 
the user’s preferences. 

As illustrated in fig. 2a, one 
can see that lextEdit has been 
localized in seven Languages, 
The “MacOS” folder contains 
the hinary and “Resources” 
contains all the localized 
resources (as well as some 
global resources like the “tens" 
files.) The file “info.plist” is the 
heart of the bundle. It contains 
the version of the application, 
the icon to be used for the 
documents the application cre¬ 
ates, as well as the application 
icon and many other parame¬ 
ters specific to the application. 

You can see the localized 
packages supported by the 
application through the Finder 
as well when you access the 
3a). 


Text Support in Mac OS X: 

International by Default 

Use CFString to Store Your Text 

Core Foundation enables internationalization through Unicode 
strings and provides abstractions that contribute to operating sys¬ 
tem independence, 


CFString and CFCharacter-Set provide a full suite of fast and effi¬ 
cient string manipulation and conversion functionality. String 
Services offer seamless Unicode support and thus greatly simplify 
internationalization. String Services also facilitate sharing of string 
data between Carbon and Cocoa applications. 

Use MLTE for Your Text Editing 
Needs in Carbon 

MITE, the Multilingual Text Engine, is available on Mac OS X. MLTE 
is a replacement for TextEdit and is a full Unicode text engine that 
uses ATSUI (Apple lype Services for Unicode Imaging), When an 
MLTE text object is created in an application, Unicode layout is 
included as well as support for 2-bvte scripts. No need to install the 
necessary T8M handlers to support Japanese, Chinese, and Korean 
as MLTE does this. No need to install scrollbars, drag-and-drop han¬ 
dlers as MLTE can provide these services as well. 

MLTE is an important piece of text rendering in Mae OS X MLTE 
supports the usual QuickDraw anti-aliased text but it can also ren¬ 
der on Mac OS X with Quartz. The result gives text-editing fields the 
look and fed typical to Mac OS X. 

You'll find more information on MLTE at: 
bttp:/ideiehper. apple. com/techpubs/macosx/Carbon/text/Muitilingu 
alTextEngine!M ultil inguallexttng inefindex, btml 

YOu'll find sample code on MLTE in the Carbon Lib SDK, down¬ 
loadable from: 
http:iicQnnect.apple.com 

What’s Next? 

If you need resources, or help localizing an application, visit: 
bttp:/fdeveloper apple. am/intlf for information. You'll find 
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“Built for Mac OS X” 

Artwork Now Available 

Now that customers have Mac OS X in their hands, 
they’ll be looking for great products to run on it. Teli 
the world that your product runs on Mac OS X by dis¬ 
playing the "Built for Mac OS X” badge on your prod¬ 
uct’s packaging. The artwork, licensing requirements, 
and usage guidelines are available on the ADC 
Software Licensing web site. 
http://developer.apple.com/mkt/swl/agreements. 
htmlttmacosx 











































New Mac OS X 
Related Releases 

Unless otherwise indicated, the following software is available from 
the Download Software area of Lhe ADC Member Site at: 
bttpd/connect. apple, com/ 

• CarbonLib L4a2 SDK 

The latest pre-rdease version of the CarbonLib 1 A SDK for Mac OS, 
is now available to all ADC Members. This SDK provides all the files 
needed to begin Carbon development. CarbonLib 1.4 supports Mac 
OS 8,6 and greater 
bttp:!/conned. applexom 

• Mail Import Scripts 1.1 

A bundle of AppleScripts that hdp you import mail messages from your 
current email program into Mail the Mac OS X e-mail client, 
hitp-.//mu, info, apple, com/swupdates. mf/annum jn 12038/ 

• Mac OS X 10,0*3 Update 

This update delivers CD-burning support for Dunes; a number of 
improvements for overall application stability; and latest version of 
the Internet file transfer service (ftpd), which features important 
security improvements. 

bftp;//asu. info, apple, com/swupdates* nsf/artnum/n 12181 / 

• Cocoa Mailing List 

The Cocoa development mailing list Ls a focal point for discussions 
on native Mac OS X application development using the Cocoa 
Frameworks: Foundation and Application Kit, Cocoa is based on 
advanced object oriented APIs that allow development in java and 
Objective-C, Subscribers to this list will be discussing frameworks, fea¬ 
tures, and technical issues specific to Cocoa application development, 
bttp://lists, apple. comfmatfmanflisHnfo/cocoa*dev/ 

• Glossaries for Mac OS X 

These are translated strings of commonly used words and phrases 
that developers can use in their applications. Download these 
updated glossaries in French, German, Italian, or Spanish. 
bttp://developer, applexom iintl! 

Developer Documentation 

The following new and updated documentation is available to help 
with successful Mac OS X application and peripheral development at: 
http://developer, apple, com/tecbpubs/ 

Inside Mac OS X: Performance 
Carbon Documentation 
Aqua Human Interface Guidelines 
Handling Carbon Events 

Understanding text input and the 'lest Services Manager in Carbon 
Unarchiving Interface Objects With Interface Builder Services 
Interface Builder Services Reference 


Text Services Manager Reference 

Multilingual iexi Engine Reference 

Navigation Services Reference 

Providing User Assistance With Apple Help 

Apple Hdp Reference 

Carbon Event Manager 

Aqua Human Interface Guidelines 

Carbon Documentation 

Developing Cocoa java Applications: A Tutorial 

Aqua Human Interface Guidelines 

Kernel Development 

10 Kit Fundamentals 

HID Device Interfaces 

USB Device Interfaces 

Technical Notes 

TN2013 - lhe plst’ Resource {Also available in Japanese) 

TN2020 - Browser Plug-ins in Mac OS X 

TN2002 - Compatibility between jDirect 2 and JDirect 3 


Technical Q&As 

QA1036 - Displaying PCI Configuration Kesister contents in Open 
Finn ware 


Sample Code 

SC - Cocoa: lbolbarSample 

SC - Sound: PCI Sound Input Driver 

SC - Interapplication Comm: BasidnputMethod 

SC - Devices and Hardware: ATA: ATADemo 


Finding Technical 
Information With Sherlock 

A pple has created a set of Sherlock plug-ins for 
searching technical documentation on its Apple 
Developer Connection (ADC) web site. You can download 
these plug-ins from the web site at http://developer.appie. 
com/techpubs/indexes/sherlock/Sherlock_Files.sit Install 
the plug-ins on a Mac OS X system by moving them to the 
Library/Internet Search Sites/Apple directory in your home 
directory. Install them on a Mac OS 9 system by dragging 
them to the Apple folder within the Internet Search Sites 
folder of your System Folder. 

There is one plug-in for each set of technical docu¬ 
mentation: Carbon, QuickTime, Mac OS X, Mac OS 9, 
hardware, and WebObjects. These plug-ins let you per¬ 
form focused searches of the latest published documenta¬ 
tion on Apple's web site in addition to using Help Viewer 
to search the documentation installed on Mac OS X. 
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Internationalization and Localization 

Continued from page 41 


resources for companies and organizations that can help you 
make the step to be international 

Remember, in order to he internationally correct in text 
rendering, you have to use Unicode. Unicode support in the 
system is achieved through MITE and ATSUl If you do 
Cocoa development you don't have to worry, all the text 
objects in Cocoa support Unicode layout and have built in 
support for Input Methods, 

And last but not least, package your application! This will 
enhance the user experience of your customers and make 
your lift easier. 


Did You Know? 

Guides for Internationalization 

pple's Technical Publications group is cur¬ 
rently working on a book that will cover inter¬ 
nationalization, localization, file encoding, and 
related issues for all Mac OS X application environ¬ 
ments. However, you don't have to wait for that book 
to find out how to internationalize you application. 

Here are several sources of information: 

• Mac OS X: System Overview. Includes a chapter on 
internationalization and multiscript support. 

• Project Builder Help. Contains a section, under 
Files, on “Customizing for Different Regions and 
Platforms.” 

• Cocoa Developer Documentation. Includes a program¬ 
ming topic on internationalization for Cocoa applications. 

• Carbon Developer Documentation. Includes several 
manuals on technologies that relate to international¬ 
ization and localization, including ATSUl, International 
Resources, and Text Encoding Conversion. These 
documents are listed under "Text and Other 
International Services" on the Carbon developer docu¬ 
mentation home page. 

You can access this documentation from the Help 
Viewer's Developer Help Center or from the ADC web 
site for Mac OS X documentation: 
http://developer.apple.com/techpubs/macosx/ 
macosx.html 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 

visit the developer Events page at: bttp://devefoper. apple.com/events/ 

Training and Seminars 

R/com Offers Mac OS X Developer Training Online 
K/cont, also known as McdiaSchool < www.niediaschooi.com > t has 
partnered with Apple Developer Connection to create online training 
for Mac OS X de velopers. The first courses to be released in June 
include "Application Development for Mae OS X/ T "Carbon 
Development for Mac OS X," and "Cocoa: The Object-Oriented 
Application Solution." All classes have been reviewed by Apple engi¬ 
neers for technical accuracy. Check out their site to take a free virtual 
seminar, to learn more about current and upcoming courses, and to 
find out about the significant discounts offered to Premier, Select, 
and Student members of the Apple Developer Connection. 
bnptjjwww. mediaschooL comiadcf 

Apple iServices 5-day Cocoa Training 
For application developers who want to learn how to develop Mac 
OS X applications using Cocoa, Apple iServices offers a five-day com¬ 
prehensive, hand-on Cocoa training course. This course uses real- 
world examples and is perfect for developers who have a general 
understanding of Object-oriented concepts and practical experience 
with the C programming language or a C-derived language 
(Objective-CJava, or C+ +). The course costs US $2,495. 
bttpiiiwww. apple. comliSenncesIlecbnicaltraininglcocoadeiKhtmi 

Developer Related Conferences 

1394 (FireWire) Developers' Conference 2000 
June 31-Aug 2, Redmond, WA 
Apple, Intel, and Microsoft are cosponsors 
bttp:/!wu'iv. I394ta. otg/Fverttsf200J DevConjindex. him 

MACWORLD Expo, New York 2001 

July 17*20 in Jacob Javits Convention Center, NYC 

Discounted exhibitor packages available 

http: ffdeveloper apple comfmktfmwny2001 . btml 

FileMaker Developer Conference 2001 
August 12-15, Orlando, FI 
More than 40 sessions and a product showcase 
http: i/www.file maker, com/devcon/ 

Various FileMaker training classes offered concurrently 
http'.ijwwu .Devcon Tra tning. com 









POWERPLANT 

WORKSHOP 


By Aaron Montgomery 


Basic Files 


How one goes about writing a 
PowerPIant application 

These Articles 

This is the fourth article in a series of articles about 
Met rowerks’ PowerPIant application framework. The first article 
introduced how the framework deals with commands, the 
second article discussed the debugging facilities of the 
framework and the third introduced windows. This article 
focuses on the file classes in the framework (opening and saving 
files). This series assumes familiarity with the C++ language, the 
Macintosh Toolbox API and the Code Warrior IDE. The articles 
were written using Code Warrior 6 with the net-update to IDE 
4.1.03 anti no other modificalions. Throughout this and future 
articles, 1 will assume that you are using the class browser and 
the debugger to explore the PowerPIant code more fully. 

Setting Up Navigation Services 

Before you can use Navigation Services, you need to do 
some setup. The first step is to modify the common prefix file to 
let PowerPoint know whether you want to always use the classic 
file dialogs, require Navigation Services, or use Navigation 
Services if it is available and the classic dialogs otherwise. This 
is done in the project’s prefix file. 

CtimmtinPrvlljt-h 

//If PF Target Carbon 

//define PP_StdDialogs Option \ 

FF_St d nia1oga NavSarvicesOniy 
/^define Set TryNavKprvires do I I while (false) 

#else 

//define PP_StdDialogy_Option \ 

P F_Std Dialogs^Conditional 
//define SetTryNavServiees_ \ 

PnwerPlant:rUConditionaJ Dialogs::SetTryNavServices{\ 
OkDIIOSDOD) 

If end if 


For Carbon targets, the code sets the dialogs to be 
Navigation Services at all limes and the SetTryNavServices_ macro 
does nothing. For the other targets, the code uses conditional 
dialogs. The conditional dialogs option will use Navigation 
Services if it is available anti classic dialogs otherwise, The 
SetTryNavServices_ macro tells PowerPIant to use Navigation 
services only if it has version at least l.l (PowerPIant stationery 
explains that earlier versions can cause problems). 

The macro PP_StdDialogs Option affects the 
UStandardDialogs.h header by setting die 
PowerPlant::8tandardDialogs namespace (abbreviated to 
PP StandardDialogs in the code) to equal one of 
PowerPlant::UNavServicesDialogs, PowerPIant; :UConditionaDia1ogs h 
or PowerPlant::UCIassicDialogs. When using the class browser to 
identify classes and functions, you will often find that the same 
class or func tion will appear in each of these three namespaces 
and you will need to Icxik :it the appropriate one. 

The other necessary change to the code for Navigation 
Services is the need to bad them at application startup and to 
unload them al application shutdown. This is done in 
CDocumentApp s constructor and destructor. In the constructor, 
the code uses the macro SetTryNavServices to establish what 
version it requires and then calls the function 
PP_StandardDia!ogs;:Load() In the destructor, the code calls 
PP StandardDialogs::Unload)). 

As a final touch, I have also added BNDL, open, and kind 
resources to AppResourcesjsre. This provides us with custom 
icons and the finder with information alxiut what types of files 
we can open. 

Dirty Documents 

Before discussing the methods used to open and save files, 
we will discuss how PowerPIant determines if a file has lieen 
modified (in other words, if the document is dirty). 4lie 
LDocument class has an lsModified() method which should return 
true if the file has lieen modified since last read from disk and 
false otherwise. This allows the framework to enable and disable 


Aaron teaches in the Mathematics Department al Central Washington University in Fllensburg. WA. Outside of his job, he spends time riding his 
mountain bike, watching movies and entertaining his wife and two sons. You can email him at montgoaa@cwiLedu, try to catch his attention in the 
newsgroup eomp.sys.nmaxip.puwerplant or visit his web site at madi? t 08 .niath.cwu.edu: 8080 /. 
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“Without a doubt, the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools” 

- Mac User Magazine Eddy Awards 

*A distinct improvement over Apples Res Edit. ” 

- MacTech Magazine 

“Every Mac OS developer should own a copy of Resorcerer. " 

- Leonard Rosenthal, Aladdin Systems 

"Without Re sorcerer, our localization efforts would look like a 
Tower of Babel. Don't do product without it!” 

Greg Galanas, GEO and President , Metrowerks 


"Resorcerer s data template system is amazing” 

-Bill Goodman, author of Smaller Installer and Compact Pro 

*Resorcerer Rocks! Buy it, you will NOT regret it rt 

- Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effort. 

- MacUser review 

“The template that disassembles 'PICTs is awesome!" 

Bill Steinberg r author of Pyro! and PBTools 

“Resorcerer proved indispensihle in its own creationF 

- Doug McKenna , author of Resorcerer 
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Version 2.0 


The Resource Editor for the Mac ™ OS Wizard 


ORDERING INFO 


Requires System 7.0 or greater, 
1,5MB RAM, CD-ROM 

Standard price; $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 

Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, FOs, or Visa/MC 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Red, 
International Shipping 

MATHEM^STHETICS, INC. 

PO Box 298 

Boulder, CO 80806-0298 USA 

Phone:(303)440-0707 

Fax: (303) 440-0504 

re sorcere a them ae sth eti cs, co m 


* Very fust, HFS browser for viewing file tree of all volumes 

* Extensibility for new Resorcerer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary (*aete f ) Apprentice Editor 

* MacOS 8 Appearance Manager-savvy Control Editor 

* PowerPlant text traits and menu command support 

* Complete A1EF sound file disassembly template 

* Big-, little-, and even mixed-endian template parsing 

* Auto-backup during file saves; folder attribute editing 

* Ships with PowerPC native, fat, and 68K versions 


• Fully supported; it’s easier, faster, and more productive than ResEdit 

• Safer memory-based, not disk-file-based, design and operation 

• All file information and common commands in one easy-to-use window 

• Compares resource files, and even edits your data forks as well 

• Visible, accumulating, editable scrap 

■ Searches and opens/m arks/sel eels resources by text content 

• Makes global resource ID or type changes easily and safely 

• Builds resource files from simple Rez-like scripts 

• Most editors DeRez directly to the clipboard 

• All graphic editors support screen-copying or partial screen-copying 

• Hot-linking Value Converter for editing 32 bits in a dozen formats 

■ Its own 32-bit List Mgr can open and edit very large data structures 

• Templates can pre- and post-process any arbitrary data structure 

• Includes nearly 200 templates for common system resources 

• TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

■ Full integrated support for editing color dialogs and menus 

• Try out balloons, l ictb T s, lists and pop ups, even create C source code 

• Integrated single-window Hex/Code Editor, with patching, searching 

• Editors for cursors, versions, pictures, bundles, and lots more 

• Relied on by thousands of Macintosh developers around the world 


Tb order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website, 

www.mathemaesthetics.com 













the Save and Revert menu commands appropriately. In order to 
make the system work, we will need to use the SetModifiedQ 
functions when the file has Ixxm saved to the disk and when it 
has been modified by die user. 

The first change to the axle adds an iAmModified data 
member to the CHTMLTextView class. The LTextEditView class 
from which il derives provides the virLual method 
U$erChangedText() which will be called anytime the user types 
(or deletes) something from ihe LTextEditView. 

UseiOungalTmO in GFTTMLltauVicw.cp 
void CHTKLTextView:rUscrChangedText() 

( 

if (IsKodifiedO = false) 

I 

SetOpdat^€omraandStatus(tn]e); 

SetModitied(true); 

I 

1 

The axle only needs to do something if this is the first 
modification. In that case the axle tells the menus that they will 
need to lx 1 updated and then sets the objects flag to indicate that 
it has been modified. If you directly manipulate the text in an 
LTextEditView, the UserChangedTextO method will not be called 
automatically. In our case, the lnsertTag() method needs to 
indicate that it has modified the document and it does this with 
a call to UserChangedText(). The IsModifiedQ and SetModifiedf) 
methods of CHTMIView are inline functions which access and set 
the object’s flag. 

In the CTextDocument class, we change the lsModified() 
method so that it checks its CHTMLTextView \ IsModifiedf) melluxl 
before returning a result. In addition, we update the 
SetModifiedQ metluxl so that it also calls the CHTMLTextView s 
SetModifiedO method. Note that PowerPlant does some 
housekeeping in LDocument’s SetModifiedQ method and so we 
call it from within die new metluxl definition. You could also 
just copy the code, but that would mean that you would need 
to update your code if more housekeeping was done within 
LDocument's method. 

Opening Fills 

We are now ready to consider how PowerPbmL opens and 
saves files. The code presented here is modeled on the code in 
the .stationery files provided with PowerPlant. There is one 
limitation with the strategy employed there lhat may make it 
unsuitable tor your application, I be problem arises because of 
the need to call ::NavCompleteSav9{) if Navigation Services have 
been used to save the file. The code in the PowerPlant stationery 
handles this by holding the file open on the disk until the 
document is closed. This allows the CTextDocument object u> 
save the information necessary for the call to 
::NavCompleteSave(} until the document is dosed. The 
disadvantage is that die file cannot lx manipulated by another 
application while it is held open by HTMLedrt. If you need to 
allow external tools to modify files while your application holds 
them open, you will need to adjust the axle to permit this. 


The first change in the code is the removal of some lines 
that were added in the first article. Now thaL our application can 
open files, the lines in FindCommandStatusQ which disabled the 
open command can lie removed. There is no need to change 
ObeyCominandQ since PowerPlant's LDocApplication class already 
has the necessary code. Two CDocumentApp methods are 
necessary for opening files. The first, ChooseDocument(), 
interacts with the user to determine which file should tie opened 
and the second, GpenDocument(), opens the document. We start 
with ChooseDocument{). 

UiuwcDm umt m in CDiwuniiiitAfip.cp 

void 

CftorutnentApp: :ChooseI>ocuneiit () 

I 

LFileChooser theChooser: 

NavDialogGpiions* theOptions * 

theChooaer.GetDialogOp l i cm3 (); 

if (theOptiona 1- 0) 

I 

tlieOpt lonn->dialofcOptionFlags |* kNavSelectAllReadableltenn 

if (theChou&et.AskOprnFilefLFileTypeLisi())) 

[ 

AEDescList theBocList: 

theChooser,GetFileDeseLis L(fhnDocList); 

SondAROpsnDocList(theDocidst1: 

I 

1 

There are really three LFileChooser classes, one in each of 
the namespaces mentioned earlier. At the top of the source file, 
the axle indicates that the one in PowerPlant::StandardDialogs 
should lx: used, Therefore, the actual class used will l>c 
determined by the macros in the prefix file. All three of die 
LFileChooser classes allow you to obtain a pointer to a 
MavDialogQptions structure. 4 Ihe pointer will be 0 if the 
application is using classic dialogs If the application is running 
under Navigation Services, we adjust the flags so that All 
Readable Items is the default choice from the popup menu in 
the dialog. 

Next, the code creates an LFileTypeList (the default 
constructor uses the open resource with ID I2K), In the rase of 
HTMLediL only TEXT tiles can lx* opened. If AskOpenFileQ 
returns true, then the user requested a file be opened, and the 
code gets the AEDescList that describes the file from theChooser 
and sends an Open Apple Event to the application. PowerPlant 
will convert this Apple Event into a call to GpenDoeumentQ. One 
nice feature is that there was almost no need to write separate 
code for the three possible situations (Navigation, Conditional, 
and Classic). Furthermore, you obtain the ability to open 
multiple files under Navigation Services withom doing any extra 
work: PowerPlant will turn these lists into a sequence of 
individual open commands. We now turn our attention to the 
place where the document is actually opened. 

OpcrtDocumentO in QXiuimemApp tp 

void 

QJocumentApp:: OpenDocumcmt 

FSSpee 4 inHseFSSpei:) 
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Marketing Rule no. 


MAKE YOUR PRODUCT EASIER TO BUY, YOU'lL Sill MORE OF IT- 


You mny have developed the best software in the world, but if nobody 
knows about it, or can find it, you won't sell much of it. With eSellerate, 
your application literally sells itself. Providing your customers with the power 
of instant gratification. And providing you with an opportunity 
of nearly limitless potential, ww w, e sell erafe.net 6 
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( 

LDocuraen t * rheDoc * 

LDocument:;FindEyFileSpec(*inM3cF55pec )i 

if (theDoc 1“ 0) 

l 

ValidateObject_(theDoc) j 
thoRoc * >HakeCuc rent{); 

I 

else 

try 

( 

theDoc ® NEW (TFextDocumerit (this * iriHacFSSpee) : 

ValidateQbjfcct_(theDoc): 

I 

catch(LExceptionk thelrr) 

I 

if [thoErr.GetErrorCodef) 1” noErr) 

i 

throw; 

I 

I 

I 

First, the code lrie.s to find the document from among the 
curreniiy open documents using the static IDocument method 
FindByFileSpec(). JF FindByFileSpecQ returns a pointer to an 
IDocument, then the code brings it to the Front and is finished. 
If the document is not already open, then the code needs to 
create a new document and other than the error 1 land ling, this 
is accomplished to CTextDocumenfs constructor. 

The error handling code deserves some mention here. The 
constructor of CTextDocument may throw an exception if the 
document contains more than 52K of text. While this problem is 


5F0TL1QNT 

seven times faster 


free demo 
www. onyx- tech. com 


Find memory errors automatically in source 
Code Fragment Support 
Leak Detection 

ESP Toolbox Parameter Checking 


handled in the OpenFileQ method of CTextDocument (presented 
below), an exception is the only way to inform the 
□DocumentApp rhal the file was not opened. My personal 
convention is to use an LExceplion whose error code is noErr to 
indicate that everything has Ix-en handled but that the document 
is invalid. When the exception is thrown, DebugNew will report 
that the document leaked. If this were a "reap application, 1 
would spend some time determining whether this is a real leak 
or if DebugNew cannot handle exceptions thrown from 
constructors. Since this is supposed to ho a teaching article, I will 
leave this task as an exercise for the reader (watch out, 
Metrowerks pools Us memory allocations). 

You have now seen all of the significant changes to the 
CDocumentApp class and we turn our attention to the 
CTextDocument class. The CTextDocument constructor is modified 
slightly to accept an optional FSSpec. I lowever almost all of the 
work is passed on to its OpenFileQ method which is where we 
will pick up the trail. Just as LSingleDoc contains a pointer to an 
LWindow as one of its data members, it also contains a pointer to 
an LFile as another member. Tills is the real purpose of the 
IDocument class: to fie together the visual presentation 
(LWindow) with the data on the disk ( LFile). The LSingleDoc class 
assumes that each document uses only one window and one 
file. Unlike LWindow which can lx: complicated (due to die visual 
hierarchy), the LFile class is simple. If will take care of handling 
I lie file reference numbers for lx>th the data and resource forks 
and most of the methods of the class do exactly what their 
names indicate, 

i >[XTI Filer > in CTcxtOocumcnt cp 

void CTaxtDocument: :0penFi 1 HFSSpeck inlfileSpcc) 

1 

oiFile ^ nil: 

try 

I 

StBeleter<LFf 1 r i >theFileCHEW LFile(lr.Fi ); 

¥alida t eQb j ec l_(t HcF it e, Get U k 

t heFi 1 e - > Open Da t a Fu r k t f slid WrPernt): 

S i Hand 1 eBl ock theTextll (1 hcF 11 c >ReadDataFork ()); 
ValtdatcHandle_{ theTextll. Get 0 k 
VaHdateObject_ (myTextViev!; 
myTe x L ¥ I > $ etText Ka nd 1 e ft heTc x t H ) : 

myTextView >$eTMnt|ifled(false): 

ValidateObjecL_tniWInflow): 
iuWinciow'>SetDescripLor (InFIleSpcc.name): 

ttilaSpecJ fled - true: 

mFiie = thoFUr .Releasefk 

I 

catch (LExceptionfr iboErr) 

t 

if (theErr.GetErrotCoikd) err_32kLirait) 

I 

UWoda1A1erts::StopAleri(ALRT_fc S &Fila); 
throw LExceptlon(noErr); 

I 

else 
I 

throw* 

I 
i 
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YES, IT IS THIS EASY. 


At REAL Software, we like it simple. Take our award-winning product, REALbasic, for 
example. People call it the powerful, easy-to-use tool for creating their own software for 
Macintosh, Mac OS X and Windows. We call it a problem solver. You've probably said, 
"Wouldn't it be great if there was a little application that...." REALbasic fills that blank. 

It's powerful and easy to use. Beginners and professionals alike can build software 
using a single, simple design. REALbasic compiles native applications for Macintosh, 
Mac OS X and Windows without requiring any platform-specific adjustments. Each 
version of your software looks and works just as it should in each environment. 

Experiment, explore, learn and innovate as you create anything from prototypes to 
complete professional quality applications step by step. Simply drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your 
stuff great — your ideas! 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 


9 REALbasic3 

Download a free demo, www.realbasic.com 




The First goal of OpenFHeQ is to provide an LFile for the 
CTextDoctiment object* The code starts by creating a pointer to 
an LFile, The StDeleter class is analogous to the standard 
library’s auto_ptr template and it is used here so that we do not 
leak the LFile pointer if an exception is thrown. The call to the 
StDeleteFs Get() method returns the actual pointer and the 
code verifies that it is valid. 

The code then opens the data fork of the LFile, copies the 
text into a handle (the StHandleBlock guarantees Lhc memory is 
deleted at the end of the scope), anti passes Lhc handle to the 
document's CHTMLTextView object. Since the dam in die 
CHTMLTextView is fresh from die disk, the axle indicates that the 
CHTMLView is unmodified. 

ITie code dien sets the title of the window to match the 
name of the file. The mlsSpecified data member of the 
LDocument class indicates that this document has a file 
associated with it (important since it determines if the Revert 
command is valid). If everything went well, the code ms mFile. 
The call to Release() causes the StDeleter to disown the LFile 
pointer, failing to do this will cause DebugNew to (correctly) 
repon a double-delete (once when the StDeleter goes out of 
sco[K‘ and later in the CTextDocument’s destructor). 

The call to SetTextHandleO will throw an exception if the 
handle contains more than 32k characters. Since we know how 
to handle this problem here, we do so. The UModalAlerts method 
simply displays an alert staling that the file was loo big (you 
need to supply the resource and PowerPlant does the rest). 
Since lhe code needs to let the calling function know that the 
tile was not opened and there is no return value, I have opted 
to throw an LException with error code noErr. By personal 
convention, this means that something bad has happened but 
ihai no further remedies are needed. The first place where this 
error can be ignored should catch the exception and ignore it 
(you saw this in the OpenDocument(} method of CDocumentApp), 
Thai completes the tour of the code necessary to open files 
using PowerPlant. 

Although reversion of a document to the data on the disk is 
nor essential, it is easy to add this ability to a PowerPlant 
application. PowerPlant stationery assumes that you will do this 
since it provides the Revert command in its File menu and 
adding the code usually adds lit lie work. 

DuKoXTtQ in nVxtDocujncnt.q) 

void CTextDocument: iDoRevert() 

t 

VfrtirfareObject (mFiiel: 

StlEaudl nfilock theTextR(mFile ->ReadDaraFirark()} ; 

Val Ida t eiiaiui 1 r_ (theTextH. Get ()): 

Vaiidat eObj ec t _(myToxtVtew); 

myTextView->SetTex l Handle(theTextH): 

SctModifled(false); 

royTextView >RnfreshO; 

1 

The code reads the data from the CTexlDoeument's mFile 
into a handle (using a StHandleBlock to prevent a leak). Then 
it updates the text in the CHTMLTextView. The code then 


indicates that the document is now clean* The last step is lo 
make a call to RefreshQ. One important thing to lie careful 
with here is that the call to RefreshQ resolves into a call to 
::!nvalPortRectQ. This means that no actual drawing will be 
done until the next Update event is handled. Therefore, if 
you have stopped the event processing queue, then calls to 
Refresh)) will appear to do nothing. 

Although 1 will not discuss it in this article, l have also 
made the NameNewDocumentO method a little more 
sophisticated. In retrospect, this really should have been 
done in the third article where wc discussed windows. You 
might want to examine the code on your ow r n. Now we turn 
to saving (which is a little more complicated)* 

Saving Files 

All saving is handled by the CTextDocument class (and not 
by the CDocumentApp class)* Three methods need to l>e 
implemented for PowerPlant to handle saving files. The first 
method, AskSaveAsQ, presents the user with a dialog to 
determine where to save the file* The second method, 
DoAESave() : method implements as Save As operation (which 
handles the Save Apple Event). The third method, DoSave(), is 
the method that actually writes the data to the disk. 

The LDocument class has an implementation for 
AskSaveAs(). Unfortunately, it has not been updated lo handle 
the need for a ::NavCompleteSave() call under Navigation 
Services, In order to handle this, we need to rewrite the 
AskSaveAs() command as well as retain a new data member: 
myFileDesignator 

AsfcSawAsO in CTextttocunicntcp 

ftaa l ean CTextDo cuneti L:: Ask Save As E 

F55pec& outFSSpec, Boolean InRecordlf) 

I 

Boolean didSave * false; 

StDe leter <UT 1 cties i gnator) 

* heDe signst or {NEW l*F3 leDesigna tor) ; 

Va 1 3daTeSimpie0bject_(theDefdgnator.Get()): 

LheOesIgnator >SetFileTypo(GetFiIeType()]: 

NavPtalogGptiotie* theGptlone 15 
thelJcsignatar >GetDiaIogOpt lons( ): 

if (theOptions 3= 0) 

( 

theOptians->dialogOptiqnFlags |“ kNavNoTypePopup; 

I 

$tr?,5S theDefaultKame: 

if (ihcnesignator >AskDesigr»atcFilet 
CelDes c rIpr o r(theDe fau1 1 Name})) 

t 

theDesignator >Get Fi1aSpec{outFSSpeo): 
if (DsesFileSpec(outFSSpen)) 
l 

if (inRecordlt) 

I 

SendSeNAE{kA£CoteSuite P kAESave. ExecuteAE_No): 

I 

DisposeOf‘„(ityfc’i leDea i gnator); 

myFileDesignator = theDeslgsator.ReleaseO: 

DoSavcO ; 
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didSave ■ true; 

I 

Ol I5f! 

t 

if tinReeordlt) 

( 

SendAESa vpAs( outFSSpec. CetfilcTypc{) r 
ExecuteAEJHo); 

\ 

\ F {theDesignator->IsRcplncingO) 

f 

ThrowIfOSErt:_C;: FSpUeletc(fcoutFSSpec)); 

J 

if (myFileDoaignator !** 0) 

I 

ValidateSimpleObjcct JiiiyFileDeEignator): 

*nyFi leDesignator >CorapleteSave (); 

Ui Rfn>fleOf_(my FIleBes.ignutor): 

) 

myFHeDesignafor - theDesignator.RoloasfcO : 

DoAESave(outPSSpec. fiIeType_Default); 

didSave “ true: 

) 

I 

return didSave: 

I 

The first thing the rode does is to create a new 
LFileDesignator (again, a StDeleter is used to prevent leaks). 
Before interacting with the user, we need to adjust some 
settings for the dialog. Just as with the LRIeChooser in 
ChooseDocument() above, the GetDialogOptlonsQ will return 0 
if it is running under classic dialogs. We adjust the options so 
that the user will not be presented with a type popup menu. 
This Is consistent with the fact that we only save TEXT 
documents from this application. The code also sets the 
default name for the file to the name of the window. 

The call to AskDesignateFileQ returns true if the user has 
decided to save the file (and false if they cancel the dialog). 
All the information obtained from the dialog is available 
through theDesignator. The first thing we do is set outFSSpec 
to the FSSpec obtained from interaction with the user. Then 
we determine if the document’s existing file is being 
overwritten or the document is writing to another file. 'The 
two possibilities are similar and we discuss them in parallel. 

In both cases the first thing the code does is to send the 
application an Apple Event if the application’s Apple Events 
are being recorded. The actual Apple Event sent is different, 
but the code is very similar. The parameter ExecuteAE_No 
indicates that the Apple Event should not be executed once 
it is received. This Ls appropriate since the command is being 
handled here and there is no need for the code to save the 
file twice. 

If the user is saving to a different file and thaL file 
already exists, then the file needs to be deleted and this is 
done next f in the second branch). Now iL is time to handle 
the changes to the myFileDesignator data member. If we are 


overwriting our original file on disk, then the old 
LFileDesignator is deleted and the new designator is saved. 
Since the file is not being closed, die code does not need to 
call CompleteSaveQ, in the other case (where the file on the 
disk is changing and the LFileDesignator is not 0) the code 
calls CompleteSaveQ before disposing of the old 
LFileDesignator. Next either DoSaveQ or DoAESaveQ is called. 
In both oF these cases, the function will then return true 
because the file has been saved. 

Next we examine the DoAESaveO method. This method 
implements a Save As command and calls DoSaveQ to do the 
actual work of writing to the disk. Almost all of the code is 
generic and you should be able to use it “out of the box.” In 
fact, only the GSType^Creator constant is application specific 
and could easily be factored into a call to a new virtual 
function with the name GetCreatorTypeQ. 

EXiAFXaveO in CTcAlDocumcnt.cp 

void CTextBocument::OoAESave( 

F$Spe£& inFIleSpec, OSType lnFileType) 

I 

Disposed? (mFile): 

misSpeeifled = false: 

5tDeleter<DH1e>rheFile(NEV LFUe(inFiteSpec)); 

ValidateObjecl_(tboFne.Get()): 

OSType theFIieType = CorFIleTypeO; 

if finFlleTypa 1= fiieTypc_I)e£ault) 

t 

theFi1eType = inFileType; 

I 

theFlle ->Creatt*Ht i wF 1 le(0SType .Creator, thoFlleTyp *}; 

th eF i I e - > Ope nDat a ]- k M t k {F Rd W r Pc 1 nn): 

rheFile->OpenResourceForMfsRdVrPerin): 

miile - theFile,Release(); 

DoSaveO; 

Val idateObject_ (mW t tiriou); 

mUindov >SetDescriplor(inFileSpec.name): 

tnlsSpecified * true: 

I 

Since this is a Save As operation, the code first 
eliminates the existing LFile object. This does not delete the 
file on the disk, but it will dose the file if necessary. Notice 
that this is done even before we know that the new file is 
valid. My reasoning is that after an attempted Save As 
command, fhe goal is to protect the original file's data (anti 
prevent a Save command from clobbering it). The Disposed 
macro will set the mFile data member to 0 and setting 
mlsSpecified to false will prompt the user with another 
AskSaveAsQ dialog iT they try to close the window after a 
failed Save As command. 

Next, the code creates the file on the disk (with another 
StDeleter). Once we know the file has been successfully 
created and opened, the CTextDocument object will take 
control of the LFile pointer {again the call to Release(> is 
important to avoid a double-delete). The DoSaveQ command 
expects that both the resource and data forks of the file are 
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open for writing. Once DoSave() writes the cicini to the disk, 
the document’s window title is updated and its mlsSpecified 
data member is set to true. We now turn our attention to the 
one method that requires knowledge of the data layout in the 
files: DoSaveQ 

DoSavcQ in ncxtDoeumnitrp 

void CTextDocumpnt t : JloSa v e () 

I 

Vat idateObject_{myf ext View); 

Handle tbeTextK = myTextViewOGetTttxtHandlaO; 

ValidateHandie_(tbaTextHj; 

Size theTextSize 55 ::GetRand1cSlzeftheTextH); 

StHaMleLociker th&Lock {iheTextli); 

Val t da teObject_ Ensile ); 

ntFtlc >WriteDataFork(*theTextH f theTextSize)! 

SelHodified(false); 

I 

Saving text files is rather simple: gel a handle to the text 
and write it out to the files data fork. The last line indicates 
that the document currently matches the data on the disk. 
Somewhat anti-climatic, but it works. The actual PowerPlant 
stationery file saves some information in the resource fork as 
well, but I will leave that for you to explore on your own. 

Concluding Remarks 

Although Opening, Reverting and Saving files requires a 
significant amount of code, most of the work is done by 
PowerPlant. In fact, of the methods you need m implement, 
most of them can be lifted almost verbatim from the 
PowerPlant stationery files. At this point, I think I have 
covered the code presented in the PowerPlant Advanced 
stationery file (with a few omissions that you should be able 
to work out using the class browser and debugger). In the 
next article (the fifth of this series), 1 will spend some Time 
talking about control classes which can be used to liven up 
your dialogs. Once that topic is covered, I feel I will have 
covered the essential core of PowerPlant. At this point, l will 
reiterate my request that people should indicate what topics 
they would like to see. Here is a short list of topics I have 
considered: more on menus, more on panes, threads, drag 8c 
drop, tables, actions (and undo strategics), Apple Events, 
contextual menus, 1 am flexible and willing to look at other 
topics if they are suggested, 

PowerPlant References 

1 could not find as many references on hies as on some 
of the other topics, there is a single chapter in The 
PowerPlant Book entitled “File I/O". You should also spend 
some time sifting through the source code of PowerPlant as 
well as the example files (there is a StdDialogs demo as well 
as a Text Document demo). ffil 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Back In Action 


Working with Wired Actions 


Introduction 

The previous four QuickTime Tmlkit articles have focused 
largely on two topics; how to create and manipulate sprites, and 
how to attach dynamic, interactive behaviors to sprites. Interactivity 
is one of QuickTime's greatest assets and pediaps its most significant 
advantage over competing media architectures. And no doubt, 
wired sprites are the cornerstone of Quicklime interactivity. As 
we've seen, we can do some pretty nifty things with just a few' event 
ami action atoms placed in the right locations in a sprite track. 

In tliis article, we re going to take one more kx>k at wired 
actions. 1 want to consider a few of the event tyf>es and actions 
recently introduced in QuickTime *j, and l especially want to consider 
how to use wired actions with oilier kinds of tracks. So far, all the 
actions we've enaxiuntenxl have l>een triggered by some event 
involving a sprite (for example, clicking on the sprite) ora sprite track 
(for example, loading a sprite track key frame). Beginning in 
QuickTime 4, however, it s also possible to attach wired actions to 
Quicklime VR nodes and hot spots, to text in text tracks, anti to flash 
content. Lei's lake a moment to see what we can do here. 

QuickTime VK supports two general kinds of'wired actions; < 1) 
actions that apply io a partiallar ntxle, and (2) actions dial apply to 
a particular hot spot in a ncxle. Hie nfxle-sjxxilic actions can lx 1 
attached to idle events (so dial an action can be triggered 
periodically) or to frame-loaded events (so that an action can lx 
triggered when the ncxle is first entered). We could for instance, 
attach an action to a frame-loaded event to set the initial pan and tilt 
angles that are displayed when the user enters the ncxle Similarly, 
we could attach an action to a frame loaded event to start a sound 
track playing when the user enters the ncxle. In addition, we could 
use idle event actions to dynamically adjust the balance and volume 
of that sound as the user changes die pan angle of the movie; this 
provides an easy way to make a sound apjxar to emanate from a 
specific location in a ncxle (which is sometimes called directional 
sound). Or, we could adjust the pan and till angles of some other 
QuickTime VR movie, so that panning and tilting one panorama 
caused similar panning and tilling in a second. 

We can also attach wired actions to hot spots inside of 
Quic kTime VR nodes. We can configure these actions to be triggered 


by a variety of mouse events, including moving die mouse over a hot 
sjxx, moving the mouse out of a hot spot, and clicking die mouse 
within a hot spot Once again, the actions ihat are triggered by these 
events can lx any actions supported by die QuickTime wired anions 
architecture, such as starting and stopping sounds, enabling and 
disabling tracks, changing pan and tilt angles, and so forth. 

QuickTime allows us to attach wired actions to a text track, 
giving us wired text. Consider, for instance, the movie shown in 
Figure 1 litis movie contains a text track that's wired to displays die 
amount of memory currently available in the application's heap. (The 
text track is u]xlated every two seconds by an idle event action.) We 
can use this movie to track the memory usage of any QuickTime- 
savvy application. 



Figure 1 . A text track displaying the a/plication s free memory 

Or consider the movie shown in Figure 2, which also contains 
a single text track. This time the text track is wired so that clicking 
on the word ‘'Apple* launches the user's default web browser and 
loads the URL <1 ittp;//www.apple.cc>m/>; similarly, clicking on the 
word “CNN" loads the URL <hup://www.enn.com/>. 



Figure 2; A text track with hypertext links 


Tim Monroe works in the QuickTime engineering team at Apple Computer, Inc. You can comat t him at monroe@apple.com. 
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Finally, we can attach wired actions to items in a Flash 
track. Flash is a file format developed by Macromedia, Inc. for 
displaying vector-based graphics and animations. It's especially 
popular for web-based content delivery, since it combines 
compact data size (and hence speedier downloads) with quick 
rendering on the client, advanced graphics manipulations, and 
support lor mouse-based interactivity with the graphics objects. 
In QuickTime 4, Apple added a Flash media handler ihai 
provides support for Flash graphics, animations, and interactivity 
inside of QuickTime movies. In addition, QuickTime 4 added 
the ability to attach wired actions to dements in a Flash 
track, thereby supplementing the native Flash interactivity. 
So, for instance, we could use Flash graphic elements 
(instead of sprites) to provide a user-interface for a 
QuickTime movie. 

Unfortunately, we don’t yet know enough about the 
structure of QuickTime VR movies or Flash tracks to know 
where to insert event atoms. As a result, well have to 
postpone our hands-on work with wiring VR or Flash 
content. Bui we do know how text tracks are put together 
(see "Word Is Out" in MacTech, November 2000), so here 
we'll learn how to add some interactivity to our text tracks. 

Our sample application this month is called 
QTWi red Actions. The Test menu of QTWiredActions is 
shown in Figure 3- The first menu item creates the wired 
text movie shown in Figure 2. The second menu item 
creates the memory display movie shown in Figure 1 


Test 

Make HyperText Mouie- 

m 

Make Memory Display Mouie.,. 

mi 

Make Bouncing Icon Mouie... 

mz 

Make Colliding Icons Mogie... 

n* 


Figure 3 The lest menu of QTWirettActions 


The next two menu items create two more sprite movies, 
which use wired actions and operands ro make sprites react 
"physically 1 ’ with the movie rectangle and with one another. 

Text Actions 

Let’s begin by investigating a lew of the ways in which 
we can use wired actions in text tracks. In general, we attach 
an event atom to a text media sample by concatenating the 
atom container that holds the event atom onto the media 
sample data* (We’ll see exactly how this works in a moment.) 
The event atom can specify any of the kinds of events that 
we've considered so far, including mouse-click events, 
mouse-over events, frame-loaded events, and idle events. 
These wired text samples work exactly as you’d expect; for 
instance, if a text sample contains a mouse-click event atom, 
then the associated actions are triggered when the user clicks 
the mouse button while the cursor is within the bounds of 
the text track. 


Sometimes, however, we d like to handle user events 
that involve only part of the text displayed in a text sample* 
Consider once again the text movie shown in Figure 2. In 
this case, we want to trigger actions only when the user 
clicks on specific portions of the text data (namely, the 
strings “Apple’’ and “CNN"). To handle this kind of wiring, 
QuickTime supports a class of atoms called hypertext atoms. 
The goal here is to provide the sort of hyperlinks that you 
typically find in web browsers or other HTML-based 
applications. By clicking on a hypertext link in a text track, 
the user can launch the default web browser and navigate to 
a specific URL, by Triggering the KActionGoToURL action. But 
in fact hypertext atoms can contain any kinds of wired action, 
not jus! kAcitonGoToURL actions. So Lite user’s actions can just 
as easily (for ins la nee) trigger a jump forward or backward in 
the movie, or cause some changes in an external movie* 

As you can see in Figure 2, QuickTime automatically 
sets the color of hypertext links to the familiar browser- 
default blue and underlines the hypertext. Both of these 
provide visual cues that the user can interact with that 
segment of text. QuickTime also provides wired actions that 
allow us to change lire color of a segment of hypertext, for 
example when the user rolls the cursor over that segment or 
after the user has clicked on the link. Figure 4 shows the 
same hypertext movie (this time on Windows) with the 
cursor resting over the first hyperlink. 



Figure 4: A selected hypertext link 


Adding Actions to a Text Sample 

A text media sample consists of a 16-bit length word 
followed by the text of that sample. Optionally, one or more 
atoms of additional data (called text atom extensions) may 
follow the text in the sample. The length word specifies the 
total number of bytes in the text (not including the 2 bytes 
occupied by the length field itself or the length of any of the 
optional text atom extensions). The text atom extensions are 
organized as “classic" atom structures: a 32-bit length field, 
followed by a 32-bit type field, followed by the data in the 
atom. Here, the length field specifies the total lengih of the 
atom (that is, 8 plus the number of bytes in the data). All the 
data in a text extension atom must be in big-endian format. 
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Whether we use n hypertext atom or any of the standard 
types of event atoms, we add the event atom to a text media 
sample in the same way, by attaching the atom container that 
contains the event and action atoms to the text media sample 
as a text atom extension. Figure 5 shows the general 
structure of a text media sample that contains a text action. 


1101 _ 

A traditional mcvie, 
whether stored on film, 
laser disk, or tape, is a 
continuous stream of 
data, A QuickTime 
movie can be similarly 
constructed, but it need 
not be: a QuickTime 

s£zv 
typ* 

ctfrirt coracami 


figure 5 ihe structure of a wired text media sample 

If we're given a text media sample and an event atom 
container, it’s quite easy to wire that atom container to the text, 
We simply need to determine the lengths of ihe media sample 
and the atom container, enlarge the text media sample to hold 
all of its existing data and the atom container, plus the 8-byte 
atom header shown in Figure 5. We set up the atom header as 
appropriate and then copy it and the atom container into the 
enlarged media sample, 

The size of a text atom extension for wired actions, of 
course, is the size of the atom container plus the size of the atom 
header (8 bytes). The type of the text atom extension can be one 
of three values. If the atom container holds a frame-loaded event 
atom, Then the type of the text atom extension should lx: set lo 
kGTEventFrameLoaded. if the atom container holds any other 
standard event atom (including an idle event atom), then the 
type of the text atom extension should he set lo kQTEventType. 
Finally, if the atom container holds a hypertext event atom, then 
the type of the text atom extension should he set to htxt. 
Currently there is no symbolic constant for this value defined in 
any of the public QuickTime header files, so I've included this 
definition in the file QTWiredActions.h: 

^define kHyperTmTextAtGBiType FOUR CHAR CODE (* lit x t T ) 

Listing I shows our definition of the function 
QTWired_AddActionsToSample, which adds an event atom 
container lo an existing text media sample. Nolice that die 
function parameters include the text media sample, tire event 
atom container, and the type of atom extension. This type 
should be one of the three recognized types for text atom 
extensions that specify wired actions. 

listing 1: Adding wired actions to a text media sample 

(/l'Vt r ifi:d_Ai!ilAL’tic)ii'iToS:iiiipk- 

static OSErr QTWire<LAddActioneToSample (Handle theSawpIe. 


N umber of bytes of text 


Text 


Text atom extension 


QTAtoniConrainer theActions, SInt32 theAtomExtType) 

I 

Ptr myPtr = NULL; 

Ion g rnyTla nd 1 eLc ngt h ; 

long my Container Length; 

long (nyNewLength; 

OSErr myErr - noErr; 

if ((the Sample = NULL} || (theActions “ NULL)} 
return (pa rainErr): 

rayEandleLength = GetlluiidleSizeUhcSasnpIe); 
tEyCuntaiuerLength “ CetllandleSize ((Handle) itieAct ion.g); 

myNewLength = (long)(sizeofClong) + sizeof (OSType) + 
myContainerLength); 

SetEand 1 eSI ze(theSamp]e♦ fmyFtandlnLnngr.h * myNewLength)); 
myErr = MemError(); 
if (nryErr 1= npErr) 
goto bail: 

HLockftheSample); 

// get a poimer to the beginning of the new block of space added to the sample 
// by the previous call to Sci Handles j/je. we need to format that space as a text 
// atom extension 

my Ptr ■* ‘theSample + myHantfleLength; 

// set the length of the text atom extension 

’[long *}myPtr = EndianS32 NtoBC(long)(sizeof(long) + 

sizeof (OSType) * otyContainerLength)); 
rayFtr += (siacof (long) J t 

it set the type of the text atom extension 
*(GSType *)ntyPtr “ EndianS32_NtoB(theAtomExtType): 
myPtr 1“ (aizeof(QSType)3; 

// set the data of the text atom extension; 

// we assume that this data is already in big-endbn format 

KLock((Handle)theActions): 

BlockMove(‘theActions. myPtr, ittyCoutainerLengLh); 

HUnlock((Handle)theActions): 

HUnlock(theSaifiple): 

ball: 

return (nryErr): 


For more information on working with atoms, sec *The 
Atomic Cafe* in MacTecb, Septetnlxrr 2000. 

Creating Text Actions 

As we've just seen, we add a wired action event handler to 
a text sample by adding a text atom extension of type 
kQTEventFrameLoaded or kQTEventType lo ihe end of the sample; 
ihe data in the texi atom extension is ihe atom container that 
holds the information about the wired actions triggered by some 
event. So, our task boils down to this: find the data in a text 
sample, create an amm container holding information about the 
desired actions, and then append a text extension atom whose 
data is that atom container to the end of the texi sample data. 
Then we replace rhe previous texi sample with the new one in 
ihe text track. 

Listing 2 shows the code that handles the "Make Memory 
Display Movie...’" menu item. 

Listing 2: Handling the "Make Memory Display Movie...* 
menu item 

QTApp HandkM rnu 

case IDH_KAKE_HEH_DISFLAY_M0VIE: 

myPrompt - QTUtils_ConvertCTuPascaISti:ing(kHI>SaveFi:oiEpt); 
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myName - QTUtils„GonvertCToFascalString(kMDKaveFn^Knnic)} 


// dicit a flk frt)m the user to save the new movie into 

QTFrantfc PurFi 1 1 (rnyPrompt , myNane, kinyFile. 4ayIfiSelected, 
tuny lafieplacing); 

U create u text movie that displays the amount of memory free in the application 
heap 

if (mylsSeleeted) t 

my Err « QTWired CreateMemoryDiaplayWovrct&myFi le) : 
if (myErr — noErr) 

QTtfircd_AddActionsToTextKovie{itwyFile. theKenuItsat): 


myisHandled * true; 
break; 


Wc dnnt need to consider rhe function 
QTWired CreateMemoryDisplayMovie in detail, since its really just 
a variant of the GTTexLAddTextTrack function we considered in 
an earlier article. In the present case, we set the initial text in the 
text track to the single character “(T, and we set the font to 4H- 
point Times-Roman (using the constant kFontIQTimesL 

The interesting work in Listing 2 is done by the 
QTWired. Add ActionsToTextMovie function, which creates the 
appropriate wired action atom container and then calls 
QTWired_AddActionsToSample (defined in Listing 1) to append 
that container to the first (and only) text media sample in the tile 
created by QTWired CreateMemoryDisplayMovie, Listing 3 shows 
our definition of QTWired. Add ActionsToTextMovie. 


listing 3: Adding wired actions to a text movie 

QTWlfecL_AddActk»nsTt>TexI Me>vic 

OSErr QTWired Add ActionaToText Movie 4 

fFSSpnc ' I hcFSSper * Hint16 FheMpmiitem) 


I 


abort 
short 
Movie 
Track 
Media 
TimeValue 
TimeValue 
TimeVidue 
TimeVa1UC 
TimeValue 

Text UegcrlptionffamU-e 

Handle 

short 

Fixed 

QfTAtomContainer 

QSErr 


myResID = U: 
myResRetNum - -1: 
myMovie “ NULL; 
myTrack " NULL: 
myttedia = NtILL: 
niyTrackOffsf.r; 
myMod S aTI ire; 
my £ e in p 1 e Hu rat i ou; 
mySelectionDuracion; 
myNewHediaTiine: 
myTextUeae - NULL: 
mySample = NULL; 
mySampleFlaga; 
myTrackEd \ tRate; 
myAcr lows “ MULL; 
myErr = noErr: 


// open the movie file for reading ;md writing 

myErr - UpenMovieFi!e(theFSSpec, AmyResRefNum, fsRcWrPerm); 

if (myErr 1- noErr) 
goto bail; 

myErr = NewMovieFromFitet^rayMovSe. myResRerNum. IfBiyKeiiiJJ. 
NULL. ncvMovIoAelive* NULL); 

if (myErr f” naErr) 
goto bail; 

// find first text track in the movie 

myTrack - GetMovielndTrackTypeCmyMovie. kindexOns, 
TextMediaType. movieTrackMcdiaTypc); 

if (myTrack = NULL) 

goto bai1; 

// get first media sample in the text track 

myMedla *= GetTrackHedia(myTrack); 

if (myMedia — NULL) 
goto bail: 
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myTrackOffset « GetTcackOf1 set (myTrack) ; 

myMad UTIme « TrackTimeTottedisTiine (myTrackOffset, myTrack); 

// allocate some storage hi hcild the sample description for l!ic text track 
ayTextDesc = (TexiDescr I pr ionHandle)NeuHflndle(A): 
if {ntyTextDesc NULL) 
goto bail: 

roySample ” NewHandie(Q); 
if (mySample — HULL) 
goto bail: 

myErr “ GetMedlaSample(myMedia, mySample p 0. NULL, 

myMedl&Time. NULL, &mySamplf.DiJfatlon. 

(S amp1e Desc rip t i tmlb rid 1 e} m yTe xt tie a c , Nl ILL, 

1. NULL, itmySainpleFlagii) : 
tf (myErr 1= noErr) 
goto bail; 

// add actions m the first media sample 
switch (theMenuliem) t 

case IDM_HAKE_HYFERTEXT_HOV1E; 

// create an action container for hypertext actions 
myErr * 

QTWired Great eHyperTextActionContainerUinyAt:lions): 
if (myErr t-* noErr) 
goto ball: 

// add hypertext actions to sample 

myErr - QTWired„AddActionsToSa!iiple(tnySainplr, myActIon*:. 

kHyperTextTextAtomType): 

If (myErr 1“ noErr) 
goto ball; 
break: 

case IDM_HAKE JfEM_DlSPLAY_MOVIE: 

// CRflte an action comaincr for wired actions 
myErr - 

QTW5 red CreateNemoryDisplayActionContainei(fcmyAeLions): 
if (myErr 1“ noErr) 
goto bail: 

// add actions to sample 

myErr “ GTWired^tidActioneTa$ampIe(mySat»ple, inyArtinns. 

kQTEventType): 
if (myErr !" noErr) 
goto bail; 
break: 

default: 

myErr - paramErr: 
goto bail; 


// replace sample in media 

uiylrackEditRatc ” GetTrackEditRate(myTrack, myTreckOffset); 
if (GetMoviesError () !® noErr) 
goto bail; 

GetTrackNextInterestingTimeCmyTrack, nexiTlneHodiaSiimple | 

nextTimeEdgcOK, myTrackOffseL. fixedl, NULL. 
RmySelectionDuration); 
if (GetNov tesRrrerf) != noErr) 
goto bail: 

myErr ^ DeleteTrackSegmetU (myTrack. ntyTrarkOf fust, 
mySelectionDuration): 
if (myErr I* noErr) 
goto bail: 

myEr r ■ Keg 1 riMod IoRd its (myHedia); 
if (myErr I* noErr) 
goto bail: 

myErr - AddMediaSaraple( rayHedia, 
mySample, 

0 , 

Get Hand leSize (mySample), 
mySampleUuration* 

(SampleDeec riptionfiandle )myTextDesc * 

1 . 

mySampleFlags, 

&niyNewHedlaTitne): 
if (myErr != noErr) 


goto bail; 

myErr “ EndMediaEdita(myMedia); 

if (myErr 1= noErr) 
goto bail; 

// .idd the media to the track 

myErr — InsertHedialntoTruck(myTrack, nyTrackOffset. 

myNewHediaTlme, mySelcet lonDuration, 
mylrackEditRate): 

if (myErr != noErr) 
goto bail; 

// update the movie resource 

myErr = UpdaieMovieKesoureeiinyMovle, myRenRefNum. myReelD, 
NULL); 

if (myErr 1 = noErr) 
goto bail: 

// dose the movie file 

myErr = CloseMovicF 11 c (mykeaEefNiim): 
bail: 

if (myActions != NULL) 

(void)GTDisposeAtomContainer(myActions): 

if (mySampln ! = NULL) 

Disposeilatidle(mySample); 

if (myTextDesc != NULL) 

Dispo s eHan d 1e( (Qandl e) rayTe x t De sc); 

if (nyHovie |» NULL) 

nispOBcHovie(myMovie); 

return(myErr); 

I 

Everything in listing 3 is standard Movie Toolbox stuff that 
we’ve seen before, except of course for the application functions 
QTWired.CreateHyperTextActionContainer (which well discuss in the 
next section) and GTWired CreateMemoryDisplayActionContainer. 
flits latter function is in fan relatively simple. It builds an alum 
container that uses the kOperandFreeMemory operand to retrieve the 
amount of memory that is nirrently free in Lite application heap, as 
well as the kActionTextTrackPasteText wired action to paste the value 
returned by that operand into the text track. The 
kActionTextTrackPasteText action, which is new iti Quicklime 5, 
takes Three parameters: the text to paste and the beginning and 
ending locations in the text track to paste the text, Eadi time we 
paste a new value into the text track of the memory-dlsphy movie, 
we want to replace all of the existing text, so well set the second 
and third parameters to 0 and Oxffff respectively. 

There's one undocumented “gotcha" liere: in order For 
kActionTextTrackPasteText to have any effect, we need to 
explicitly enable text editing on the target I ext track. We can do 
this by executing the kActionlextTrackSetEditable wired action 
(also new to QuickTime 5). This action lakes one parameter, 
which specifies the kind of editing we want to enable. 
QuickTime currently supports three settings for the editing 
state of a text trick, which the documentation lists like this: 

{ define kKeyETirryDIsabled 0 

define kKeyEntryDirect 1 

tfdpfine kKeyEntryScript 2 
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myErr = noErr; 


(Once iihowever, these values are not defined in any 
public header file, so I’ve added those lines to the file 
GTWiredActions.hJ The default value kKeyEntryDisabled 
indicates that no editing is allowed on the text track; key 
events are passed to the movie controller (which will 
probably ignore most of them) and any editing actions sent to 
the track are ignored. The value kKey Entry Direct indicates that 
direct editing is to be enabled; this means that key events are 
passed directly to the text track (for instance, key-down 
events result in the characters being inserted into the text 
track). The value KKeyEntryScript indicates that script editing 
is to be enabled; this means that editing actions sent to the 
track are interpreted by the text media handler and executed, 
For present purposes, we want to enable script editing on 
the text track. So well execute the code in Listing 1 inside of 
OTWired CreateMemoryDisplayActionContainer. 

listing i: Enabling editing on a text track 

QTWted Memory Display Act iunC loritai ner 

myErr ** OTtewAtonConralnerfUieActions): 
if (myErr t= Hotter) 
goto bail; 

// add an evetU Atom thzi enables text editing 

my K r r Wired Util s_Ad dQTEve n t An d Ac t i cm A t oms (* T he Ac t i on b , 

kParentAtomifiContainer, kQTEveritidle. 
kActionTextTrackSetKditabie, &myActionAtom); 
if (myErc !* nofter) 
goto ball; 

myEditState = EndianK16_NtoB(kKeyErit i ySr ript) ; 
myErr * WiredUtil s_ Ad d Ac t i on P a rant© L e r A t ora (* t he Ac. tionc, 
myActionAtora , 1 , sizeof(rayEditState) * 
fcmyRditState, NOLL); 

On every idle event sent to the text track, we set the track in be 
editable (just before we execute the kAct lonTexlTrack Pas telex t 
action). In theory, we could enable editing just once in a frame- 
loaded event, Bui the idle event action is simpler to construct 
anti also ensures that we can always paste the current memory 
value into the text track (since some other action may have 
disabled editing on that track). 

The remainder of QTWired_CreateMemoryDisplayActionContainef 
is straightforward. It adds an idle event call to the 
kActionTextTrackPasteText action, using the result of the 
kOperandFreeMemory operand as the text to lx* pasted. QuickTime 
is smart enough to convert: the floating-point value returned by 
kOperandFreeMemory imo a string, as expected by 
kActionlextTrackPasteText. Listing 5 shows the complete definition. 

Listing 5: Pasting the amount of free memory into a text 
track 

QTWircd.,CrcattrMcmuryDispbyAitiunC .ontainef 

static OSErr QTWired JteeatGMenJotyDiEplayActiQnContainer 
(QTALomContalner *theActions) 

f 


QTAtora 

myEventAtom = 0; 

QTAtora 

myActionAtora *- 0; 

QTAtom 

myParamAtom - 0: 

short 

rayEd ItState; 

Ulnt32 

rayPos: 

QTAtora 

rayParoraeterAtom = 0: 

QTAtora 

myExpressiciiiAloni “ 0 

QTAtora 

rayOperandAtora = 0; 


OSErr 

myErr ■ QTNewAtoniContalner (CheActions); 

If (myErr ! = noErr) 
goto bai1; 

// add an event atom Lhar enables text editing 

myErr = WiredUlUs_AddQTEventAndActionAtoms PtheActions, 
kFa r en L A L ora T s Co nta i n & r, kQTE vent Idle. 
kActlonText Track SetKditable, AmyActionAtom); 

If (myErr t“ noErr) 
goto bail; 

jnyEdltState = EndianSlG NtoBCkXeyEotrfScrlpt); 
myErr - WiredUtil s_AddAetioftpar ameter Atom(“theActions , 
nryActioriAtora, 1, a iaeof (rayEd it State)♦ 
tayKditStole. NW.L): 
if (myErr 1= noErr) 
goto bail; 

// add an event atom that displays die amount of application memory currently 
free 

myErr = Wi redUt 11 e_AddQTEventAndActionAton3S (* theAct ions, 
kParentAiotnTsContainer, kQTEvenildle. 
MctlonTexlTratkPartteText h imyAct ion Atom); 
if (myErr noErr) 
goto bail: 

// first parameter the text to he pasted 

myErr = Wi redUl IIk, AddActlonParameterAtGiiii *theActionii♦ 
myActionAtora, 1. 0. NULL, MnyParameierAtom) ; 
if (myErr != noErr) 
goto bail; 

rayKrr = tfiredUtils_AddExpreEEioFiCDnla I norAtomTypef 
'theActions, myParameterAtora, 
imyExpressionAtom): 
if (myErr 3= noErr) 
goto bail; 

myErr = QTItisertChild<"theActInns. myExpressionAtom, 

kGperandAtaniType, 1, 1, Cl, NULL, kiryOperamiAtam); 
if (myErr 1= noErr) 
goto ball; 

myErr = Ql'lnsoriCh lid (*r,hoActions, myOpe rand At om, 
kQperandtteeeMemoiy* 1, 1, Q, NULL, NULL): 
if (myErr noErr) 
goto hail: 

// parameter selection range kgin U 

myFus - EndianlJ32 NtoB(O); 

myErr - WiredUtils_AddActionPatameterAtom(*theAcLions, 
nyAeiionAlom. 2. sizeof(rayPos), &myPos, NULL); 
if (myErr T- noErr) 
goto bail; 

// third parameter selection range end (Ixffff 

myFon = EndianU32_NtoB(Uxfff£); 

myErr “ WiredUtils AddActiotiParairieterALomt * the Act ions, 
rayAer lotiAtojtt. 3, sizeof(rayPos), &myFos. NULL); 

bail: 

return(rayErr); 

On classic' Macintosh systems (that is, Mac OS 8 and 9), the 
movie created by all this axle will display the amount of free 
memory in the application heap (or essentially what you could 
determine by executing the Memory Manager function 
FreeMemL On Windows systems anil on Mac OS X, where there 
are no application heaps in the dassic-Mac seme, the movie will 
display less useful numlxns. In fact, Fm not exactly sure what 
the numbers displayed on Windows and Mac OS X represent 
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Creating Hypertext Actions 

Let’s consider now how to construct text movies that 
contain hypertact actions, like the one shown in Figures 2 and 
4. The basic ideas are the same as with constructing wired text 
movies, except that now we add a text atom extension of type 
kHyperTextTextAtomType to the end of the text sample. Also, the 
atom container that's inside of the text atom extension should 
have die structure shown in Figure 6. 



Figure 6 . 'the structure of a hypertext text atom 


As you can see, the root atom in a hypertext text atom is of 
type wtxt\ Tills atom contains one child of type htxf for each 
hypertext link in the text sample, let s rail (his child atom a 
hypertext item atom* A hypertext item atom specifies the 
information alxiut a single hypertext link in a text sample. We need 
to specify the starting point and ending point in the sample text for 
the hypertext link, and we need to specify the event and action 
atoms associated with that segment of text. So a hypertext item 
atom needs to contain at least three children, of types strt 1 , end , 
and kQTEventType. In our source axle, well use these constants: 


//define kliyperTexlTextAlonlype 
#d c- f i tie kText Wi redUb j ec t s At enti type 
//define kHyp e i: Textit enAtonTy pe 
//define kRan^eStart 
//define kRangeEtid 


FOUR^CUAl{_COaEfhLxt H ) 
FOUR_CHAk_GODEt 'wLxt') 
FCiUR_CHAR_CODE (' htxt' J 
FOUR_CHAR_CODE('strt H ) 
FOUR CHAR CODEC end ') 


There's no need to consider the function 
QTWired_CreateHyperTextActionContainer in detail. Il simply 
builds the atom container shown in Figure 6 t using hard-coded 
values for the parameter data of the kRangeStart and kRangeEnd 
atoms. Radi of our hypertext item atoms contains three event 
atoms. The first event atom looks for mouse-clicks on the 
hypertext link and executes a kActionGoToURL action in 
response. The second and third event atoms watch for the cursor 
to enter and exit the hypertext link, changing the color of the 
text appropriately, listing 6 shows the code for changing the 
hypertext color to purple when the mouse enters the first 
hyperlink. The kActionTnxtTrackSetHyperTextColor action lakes 


two parameters, which are rhe index of the hypertext lank whose 
color is to change and the desired new color 

listing 6: Changing the color of a hypertext link 

OT^IretLCr^ucHyperTextActifinContainer 

HodifierTrackGrapMciaMudeRecord myGraphicsHodeKecorti; 

myErr “ WiredUtils.AddQTEventAiidActionAtOffis(*tbeActions. 
myHyperTextAtom. kQTEventKouseEnter, 
kActionTextTrackSetHyperTextColor. ftmyAttionAtom); 
if (miyErr 1= nnErr) 
goto ball; 

my Index = EndianSjl6_NtoB(l): 

myErr = WIredUtils_AddActionParaineterAt£niiC *theActionsj, 
my Ac t i onAi out. klndexOne» si z eo f (my Ind ex), 
kraylndex, NULL); 
if {myErr [= noEtr) 
goto bail ; 

royCraphicsModeReco rd. graph i c aMode = 

EndianS!i2_NtoB (ditherCopy) ; 

myGraphiesliod ©Record .opColor,red = LndianS16_NtoU(Qx9999} ; 
myGraphicsModeRecord.opColor.green “ EndianS16_NtoB(OxODOO); 
myGraphicsModeRecord.opColor.blue - EndianSlG HtoE(Oxcccc); 
myErr — Wi redlltil s_AddActianParameterAtom(' theActions r 
rtyActionAtom, klndcxTwo. 
sizeof(myCtopbicaHodekocord), 
kmyCraphicsModeRecord, NULL) ; 

Take a look at the source file QTWi red Actio ns. c for the complete 
definition of QTWired_CreateHyperTextActionContainer. 

Key Events 

QuickTime 5 introduced a new type of event, the key event (of 
type 1 kGTEventKeyf which is issued when keys on the keyboard are 
pressed. Consider, for instance, the movie shown in Figure 7, which 
displays the ASCII character code of wliatever key the user presses. 
In the case shown here, the user lias just pressed the T key. 


u 

flSCHKey.mou S 


00 


Figure 7. A movie that displays ASCII character 
codes of pressed keys. 

A key event can Ire used in event atoms just like any of die 
caller event types we’ve encountered so far. What’s interesting 
about key events is that we can determine not only that the user 
has pressed a key, but also which particular key was pressed. 
We do this by inspecting Lite event parameters of the key event, 
using the new operand kOpe rand Eve ntPara meter This operand 
itself takes one parameter, which specifies the index of the event 
parameter we want to inspect. In the case of key events, we can 
inspect any one of 5 event parameters: 

* Parameter index I is the horizontal position of the cursor at 
the time the key event occurred, in coordinates relative to the 
text track rectangle. 
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Parameter index 2 is the vertical position of the cursor at the 
time the key event occurred, in coordinates relative to the 
text track rectangle. 


BiyErr " QIInsertChildptheActions. niyOpriatidALura, 

kOperandEventParameTer. 1, 1, t), NULL, 
^rayEventParamAtora): 

If (rayErr ! = tioErt) 
goto bail; 


• Parameter index 3 encodes tiny mtxlifier keys iliai are down 
when the key event occurs, using these constants from Events,h: 


enuin [ 
andKey 
shiftKey 
alphaLock 
optionJCey 
cemtroiKey 

1: 


* 1 « crndKc^yBit r // 0*0100 

- 1 « shifrK^yBIt, W tlxt>2tX) 

- ] « alphuLockM t* // thtHOO 

= I « optionKeyMU //0x0800 

- i « controlKeyfti I 0x I000 


For instance, if the Control and Shift keys are both down 
when the key event occurs, then the third parameter would 
be 0x00001200, or 4608. 


* Parameter index i is the ASCII character code of the key 
pressed. 


* Parameter index 3 is the virtual key code (or scan code) of 
the key pressed. A virtual key code is a value that represents 
a Specific physical key on a specific model of keyboard. As 
a result, these values are generally less useful than the ASCII 
character codes. 


We can construct the ASCII display movie in Figure 7 in 
exactly ilie same way we previously constructed the memory- 
display movie. Instead of issuing the kActionTextTrackPasteText 
action in response to idle events, we now do so in response to 
key events. And we get the text to be pasted not from the 
kOperandFreeMemory operand. but from the 
kOpe rand Event Para meter operand Listing 7 shows some of the 
code we could use to construct the ASCII-display movie. (This 
code could lx: substituted for part of Listing 3. for instance.) 


Listing 7: Adding a key event 

QTAtotn myEventFarajnAtora = 0: 

short mylrtdex; 

// add an evem atom ttm displays file ASCII code of the pressed key 

my Err * Wirfidlltils AddQTEventAndActionAtoms(*t:heAetiona, 
kP.ircn t At orals Con t a i n e r, kQTEve n tKey. 
kAe t L o fiTc x t T r a ckPa steText , AmyActionAtoto] ; 

if (ttiyErr !- noErr) 
goto bail; 

// first parameter the text to In.- pasted 

tnyErr ~ WiredUtils AddActiOnParameterAtom(*ttieActiont?, 

myAotionAtom t 1* 0, NOLL* krayPa ranse ter Atom): 

if tnyErr I" naftrr) 
goto bail; 

rayErr * WiredUt±ls_AddExpressionCofila InerAt oaType ( 
‘theActions. myFarameLetAtom, 
SrayExpressionAtora): 

tf (iiyErr !- ooErr) 
goto bail; 

myEr r = QTin a en Cb11d{* theArtIons, myExp r es siooAt om. 

kOperandAiomType, \ t 1.0* NULL, 
&myOperandAlora); 

if (myErr 1- noErr) 
goro bail; 


ray Index - EndianSI6_NioB(M: 

myErr - QTInsertChiId( # theActions, tyEvcntPararaAtom, 
kActionPararaeter. 1. 1. sizeof(nyIndex ) P 
AmyIndex, NULL); 


Notice that we add a parameter atom i myEventParamAtom) to the 
operand atom, to specify the desired index for the event 
parameter we want to retrieve. In this case, we specify the index 
4, to obtain the ASCII character code of the key pressed. 

Us also possible to use the kOpe rand EventParameter operand to 
retrieve event parameters for mouse-related events, such as mouse- 
enter and mouse-click events. With mouse events, them are only 
three available parameters, which are tlte same as the firsi three 
parameters of key events: the horizontal and vertical mouse 
jxjsitions, and the modifier keys currently down. In an earlier article, 
you may recall, we used the KOperandMouseLocalHLoc and 
kOperandMousGLocalVLoc operands to get these mouse positions. In 
QuickTime 5 and later, we can Instead use kOpo rand EventParamete r, 
if we .so desire. 


Bouncing Sprites 

In several of the previous articles, we've seen that we 
can move a sprite around inside a sprite track by altering its 
matrix, either directly (by setting the sprite's matrix property) 
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or indirectly (by performing wired actions such as 
kActionSpriteTranslate). In this section and the next, we'll 
consider a couple of ways to build on this capability. First, 
well see how lo make a sprite bounce around inside of the 
sprite track's enclosing rectangle; later well see how to 
figure out when two sprites collide with one another. Both of 
these are ways lo give a sprite “ physical" properties, so that 
it appears to react with things around it. 

Figure 8 shows (about as well as any static image can. 
1 guess) a sprite bouncing off the track's enclosing rectangle. 
The sprite is first moving down and to the right; when its 
bottom edge touches the bottom of the track rectangle, the 
sprite bounces up and continues to the right.. When any other 
edge of the sprite touches a side of the track rectangle, the 
sprite does the appropriate thing by moving back away from 
the side it touched hut otherwise continuing in the same 
direction. (In the event that two of its edges touch two sides 
of the track rectangle at the same time, the sprite would 
reverse both its horizontal and vertical directions; this would 
happen when the sprite moves cleanly into a corner of the 
track rectangle.) 


Bounce.mou 



Figure 8 A sprite bouncing off the movie edge 


Moving the Sprite 

The first Lhing we need to do is get the sprite moving. To do 
tliis. we can simply change the horizontal and vertical positions of 
the sprite during idle events. Since we'ie going to he changing the 
direction of movement when the sprite collides with the track 
rectangle, we'll maintain two sprite track variables whose values 
are the number of pixels in the horizontal and vertical direction 
that the sprite is to tie ofFset during the next idle event. We ll use 
these variables IDs: 

^define kXKoveVsrID 2000 

^define kYMoveVarin 2100 

We can set the initial horizontal and vertical offsets by adding a 
couple of frame-loaded event ac tions to the sprite, using our 
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utility WiredUtils_ AddSpriteTrackSetVariableAction (defined in 

"Wired" in MacTech, May 2001): 

#defiae kldleOffsex 2 

myErr - WiredUtils„AddSpriteTrackSetVariableAction£ 
my S ample. kPa r entAt oml sContaitie t . 
k^TEverttFram^Loaded. kXMoveVarlD, kldleOffset, 

0* HULL, 01: 

myErr _ WiredUilla_AddSprlteTrackSeLVatiableAct lon ( 
my Sample, kParentAtcmLlsContajjier. 
kqTEventFrameLoaded* kYMoveVarH). kldleOtfset, 

0. NOLL, 0): 


During idle events, well move the sprite horizontally by the 
current value of the kXMoveVarlD variable and vertically by the 
current value of the kYMoveVarlD variable. The speed of the 
moving sprite is determined both by the values of these 
variables and by the frequency with which we receive idle 
events (which, you’ll recall, is determined by the sprite track's 
kSpriteTrackPropertyQTIdteEventsFrequency property). For the 
IXRindng sprite movie, well tell the sprite media handler to send 
us an idle event every tick, and (as you can see) well offset the 
sprite in each direction by two pixels during every idle event, 
We add actions to move the sprite during an idle event like this: 

myEct ~ V i r ed U l iLtf_AddQTEventALam(mySpriteData, 

kPareniAtaalsContainer. kQTEventldle, brayliventAtora); 

my Err - QWited_AddTranslateByVariablesAction{rnySpriteffHta. 
tny Even tAt am, kXMoveVarlD. kYMaveVarlD. NULL): 


The GTWired_AddTrans3 ate By Variables Action function adds to 
die specified event atom (here, myEventAtom) an anion atom 
that translates the sprite relatively, taking the horizontal and 
vertical offsets from the sprite track variables whose IDs are 
.specified by the third and fourth parameters (here, kXMoveVarlD 
and kYMoveVarlDL Listing 8 shows our definition of the 
QTWired.AddTranslateByVariablesAction function. 

Listing 8: Translating a sprite using variable values 

CJTVi’i rrd AihlTramlat eRy VariahfI'sAitiiin 

Static OSErr QTW1 rod-AddTranslatcByYariablcsAction ( 

OTA t o mCo it t a i m? r L he Sp rite, OTAt om t hei T e r ei 1 1A l on , 

OTA i 0 m IH theXVartableID, QTAiomlt) theYVariiibleit}, 
QTAtom 1 LbeActioriAtom) 

QTAtom myAetionAtom * 0; 

QTAtom myExpressionAtom ^ 0; 

QTAtom myParamAtom = 0: 

QTAtom myOpararnrAtom - 0 : 

QTArom myOperandAtom = 0: 

QTAtom myOporatidTypeAtoni 31 0; 

QTAiomtD myVariableiD; 

Boolean myBoolean: 

OSErr myErr - paramErr: 

if (theSpritc — NULL3 
goto bail; 

// atkl a transLitr action atom to the specified parent atom 

myErr = WiredUtilE_AddActionAtom{theSprite, theParentAtom, 
XAct i onSpr it ^Translate, ^myAetionAtoin): 
if (myErr 1“ noErr) 
goto bail; 

// first parameter:get value of variable theXVariabirlD 

myErr ** WlredUUIsJWdActionPiiramtUerAtoniUheSprite. 

myActioiiAtam, kFirstFarani, 0 , NULL, finayParamAtom]; 


if (myErr 1“ noErr) 
goto bail; 

myErr = WredUti1 a_AddExp r o s r i onConta E n c r A tomType 
(thcSpriLe* itryPatcUiiALoni, 6royExptessi.anAE.cfi}; 
if (myErr 1= noErr) 
goto bail; 

myErr - QIlnsertChildEtheSprite, oyExpressionAtom. 

kOperaodAtomTYpe* 0, L 0, NULL, &myOperandAtom!; 
if (myErr 1= noErr) 
goto bail; 

myErr » QTlftsertChildtthabprite. myOperandAlam, 

kQperandSprlteTrackVariable, 1* 1. 0, NULL, 
&myOperandTypeAtom); 
if (myErr t- noErr) 
goto bail; 

tny Va r J ableTD = End i a nil 12_N r oR (t b eXVo r 1 at> 1 o T ]>); 
myErr “ QTInsertChild(theSprite. myOpe randTypeA loin, 
kActionFarumeier, 1, 1* sizeof(tnyVariablelB), 
kiayVariablelD, NULL) ; 
if (myErr 1“ noErr) 
goto bail; 

// second parameter get value of triable [htYVariihldl) 

myKrr = ifiredUti ls_AddActjqnPara«otcrAtoai(lhcSptilc, 

my AclionAlam * kSe e oml Pa r am♦ 0, NULL, &my ParamAt om); 
if (myErr I- noErr) 
goto bail: 

myErr - WiredUtils AddExpressionContainerAtomType 
(theSprite, tityParatuAtom. &myExpreEfltonAtoca); 

If (myErr 1" noErr) 
goto bail: 

myErr = QTlnst'ttChildUheSprite, tnyExpreEsionAtom, 

kOperandAtaniType. 0, 1, 0, NULL. imyOpe rand Atom); 
if (myErr !- noErr) 
goto bail: 

myErr ” QTTnGerrfihild(theSprito. myOperandAtom, 

kOperaudSprlteTrackiarlablc 1 . K 1.0. NULL, 
krayQperandTypeAiont); 
if (myErr 1= noErr) 
goto bail: 

myVariablelD - EodianUlZ^NtoB(thcYVartableTB): 
myErr = QTInsertChi Id (t hcSprit e, myOperandTypoALoti, 
kActionParufnvLot * 1, 1, alnoortiiiyVariablelU)* 
AmyVariableHL NULL); 
if (myErr != noErr) 
goto bail; 

// Uiird parameter lake (for rdaUvc tronslaunn) 

myBonlnan = faiso; 

jnyEi r “ WlredlTtUn AdrjAetionParamet^rAtomCtheSprlte. 
myAciionAtom. kThlrdParam, slxoof{myBooloanJ, 
irnyBooloaii. NULL): 

bail: 

if (theActionAtom \“ NULL) 

HheActionAtoni = myActionAtom; 

rnturn(myErr); 

I 

Here we add an action of tyjx j kActionSpriteTranslate. which 
requires three parameters: the desired horizontal translation, the 
desired vertical translation, anti a Boolean that indicates whether 
the translation is absolute or relative. For the first and second 
parameters, we add expression container atoms that retrieve the 
value of the variable with the specified ID. (For more 
information alxnit expression container atoms, see "Wired" in 
MacTech, May 2001.) 
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Detecting Track Rectangle Collisions 

So far, so good. But if this were all the wiring we attached 
to the sprite, we wouldn’t get quite the behavior we're looking 
for. When the movie was first opened, the sprite would Iregin 
moving down to the right and would continue moving in that 
direction forever. We need to add some w iring to figure out 
w hen an edge of the sprite hits an edge of the track rectangle 
and then adjust the direction of movement accordingly. In a 
nutshell, we want to add some logic thaL says: 

• If the left edge of the sprite is less than the left edge of the 
track rectangle, then move the sprite back inside ihe track 
rectangle and reverse the horizontal direction of travel. 

• If the right edge of the sprite is greater than the right edge of 
the track rectangle, then move the sprite hack inside the 
track rectangle and reverse the horizontal direction of travel 

* If the top edge of the sprite Ls less than the top edge of the 
track rectangle, then move the sprite back inside the track 
rectangle and reverse the vertical direction of travel 

* If the bottom edge of the sprite is greater than the bottom 
edge of the track rectangle, then move the sprite back inside 
the track rectangle and reverse the vertical direction of travel. 

lfs worth pointing out that a more elegant design would use two 
hf-else" statements here instead of four “if statements, since the 
opposite edges of our sprite cannot Ixrth be outside the track 
bounds at the same time. This refinement would, however, 
require a more complicated wiring. 11! leave that as an exercise 
for the persnickety reader. 

We know the dimensions of the sprite track (since we 
created it using the constants MconSpriteTrackHeight and 
klconSpriteTrackWidthl So all we really have to learn now is how 
to figure out the position of the sprite's edges. The sprite media 
handler supports these four operands, which give us the 
information we need: 

enm 1 

kOperandSprlteBoundsLeft " 3072* 

kOperandSprltefiaundsTop = 3073, 

kOperandSpriteBqimdsRlght = 1074, 

kGpe rand SpriteliotmdsBot tom * 3075 

]; 


QTWir ed_Add SideB ounc&ToSprite(ary S priteData, 

kOpe r a ndSp r 11 eB o und sTop, l * kGp e r a to rl.es sTh a n , 
kTMoveVarlB): 

QTWired JUidSideBounteToSprite{mySpriteData, 

kOperandSpriteBoundsBot tom, klconSpriteTrackHeight, 
kOperatorGreaterThan. kYMoveVarlD); 

Hie QTWired AddSideBounceToSprite function is really quite 
simple, but (as we’ve grown to expect when building w ired actions) 
a tad lengthy. Since weVe built a few wired event handlers already, 
let's jusL survey the main points. First of all, we w'ant to Install an idle 
event atom by using our utility function 
WiredUtHs_AddQTEventAndActionAtoms. The action should be a 
kActionCase action, since we want to ask whether a side of the sprite 
lies outside the track rectangle. As we .saw in the previous article, a 
kAdionCase action has a single parameter, whose data is an atom of 
type kConditionalAtomType. This conditional atom, in turn, has two 
children, an expression container atom and an action list atom. 

Hie expression container atom needs to lest whether the 
specified side of the sprite lies outside the sprue track rectangle. As 
you can see, when we call QTWired_AddSideBounceloSpiite. we pass 
in the operand that we need to use to select the side, along with the 
track limit and the test to perform (for instance, kOperatorlessThan). 
We build tile expression container atom data like this: 

WiredLlils_AddOpc?i:aU)rAtomltheSprite. myExpressionAtmo. 
t heTe s t * fcmyQp e rato rAt om); 

// first operand: the specified skkr of the sprite 

QTIttsettCbild(theSprite. myOperaforAtoau kOprrandAtoiiTypc* 1» 

1* 0 t HULL, imyOperandAtom)r 

QTIusertChild!iheSpritc. myOperandAtom. theSide. 1. I, 0, 

HULL. NULL); 

// second operand: ihe specified limit 

WircdUtils AddGperaiidAtoiii{ the Sprite, myOpe rator At ora, 
kOperandConsrant, ? t NULL, tbcLimli): 

The contents of the action list atom are pretty straightforward 
Remember that we need to perform two actions: ( I) translate die 
sprite hac k to the edge of the track rectangle and (2) reverse the 
direction of travel in the horizontal or vertical dimension. We’ve 
already seen how to construct a translate action, .so we don’t need 
to repeat that here. We can change the direction of travel simply by 
negating the value of the variable whose ID is passed Lo 
Q1Wiied_AcklStdeik)unce"raSprite. Well do that using another 
function, QTWired^AtldNeg^teVariahleActkm, defined in Listing % 


The operand kOperandSpriteBoundsLefl. for instance, returns the 
left side of the sprite's bounding box (the rectangle that encloses 
tlie sprite), in the local coordinate system of the sprite track. 

In our code, we’ll add die side-lxruncc logic to the sprite by 
making four avlis to a QTWired Actions function 
QTWired_AddSideBounceToSprite. like this; 

QTWI rcd_AddSideBounceToSpcite (mySpriteData, 

kOperandSpriteBoundsLeft. 1 * kOperatorlessThan, 
kXMoveVarlD); 

QTWi red_Add$ideBe>unceTo Sprite (mySpr Itellata, 

kOperandSprireBouniisRIgiu, kleoiiSpriteTmcJtWid t b, 
kOporatorOreaterThaii, kXHuveVarlD): 


listing 9: Negating a sprite track variable 

QTWired AUdNqpUcViriabteActkxi 
static OSErr QTWired,AddNe&ateVatiableActIon ( 

QTAtomContainer theSprite* QTAtom theParerarAtom, 
QTAtomTD thflVariablelD) 

i 

QTAloni m/AcLiouALom = 0: 

QTAiotn myExpressianAtom “ 0: 

QTAtom siyParanjAto© " 0; 

QTAtoro wyOperatorAteia - 0: 

QTAtom myOperandAtora = 0: 

QTAtom myOperandTypcAtom * 0: 

QTAtomTD myVariablclD; 

OSErr myKrr * p&ramEtt: 

if ((theSprite = NULL] || [thePa rent Atom ■=* 0)) 
goto bail: 
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my Err - tfiredUtilfi AddActionAtom[TheSprite. theParentAtom. 

kActionSprireTrackSetVariable, &my Act loti Anom) : 
if (rayF.rr I- noKrr) 
goto bail: 

// add parameter* U> die set variable action variable ID (Q'lAluiiilD) and value 
(float) 

myVariabielD - EndianU32 .NtoEttbeVariableIDh 
myErr ® QTInsertCh! Id {theSprite, myActionAtom. 

kAcrionParameter, 0. (shortJkFirsfParara. 
sizcof (uyVariaMelD) , imyVariablein, NULL}; 
if (iiyErr t= noErr) 
goto bail: 

myErr - QTXnsertChild(theSprite. myActionAtom, 

kActionParameter. 0, (shortJkSecondFaram. 0 P 
NULL, kinyParamAtom): 

If (myErr |- noErr} 
goto bail: 

rayErr “ WiredUtiis_AddExpressionContainerAtomTypeC 

theSprite, myParamAtom, &rayExpressionAtom}: 
if (myErr !« noErr) 
goto bail: 

myErr " QTInsertChild(theSprite, myKxpresaionAtotn, 

kOperatorAtomType, kOperatorNegate, 1. 0, NULL, 
^nyOperatOtAtom) : 
if (myErr noErr) 
goto bail: 

myErr = QTInsertChiId(theSprite. myOperatorAtom, 
kOperandAromTyne. 0, i, 0. NULL. 

&myOperandAtom}; 
if (myErr !* tioErr) 
goto bail: 

myErr - QTInseriChiid(theSprite, myQperandAtom. 

kQperandSpriteTrackVariable, 1, 1. 0. NULL, 
trayOperaadTypeAtotn): 
if (myErr !** noErr) 
goLo bail: 

myVariabielD = EndianU32JMtoB(theVariableiD); 
myErr = QTinsertChild(theSprite. myOpetaitdTypeAtom. 

kAetionFarameter. 1. 1, sizeof (tnyVariabielD). 
&myVariableID, NULL}; 


bail: 

roturn(myErr); 

I 

There’s nothing ttx) exc iting here; this just says: set the value of 
the variable whose ID is theVuriabkTD to the result of negating 
the value of the variable whose ID is theVariablelD. 

Colliding Sprites 

So now we've got sprites bouncing off the walls. Let's 
get them to bounce off one another as well. In specific, let's 
create a movie with two sprites, both of which have the 
bouncing logic that we developed in the previous section. 
Then, let's add some wiring m make them recoil from one 
another when part of one sprite touches part of the other 
Figure 9 shows two sprites about to collide: the sprite with 
the new 7 Quicklime logo has just bounced off the bottom 
and is moving up to the right; the other sprite is moving 
down to the left. When the sprites collide, well reverse the 
horizontal direction of travel of each sprite unless they are 
traveling in the same horizontal direction when they collide. 
And ditto for the vertical directions of travel. This logic gives 
the sprites a nice fed as they bounce around. 
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But how do we know when two sprites collide? Well, we 
knew the coordinates of each of the corners of a sprite 
(using the operands we encountered in the previous 
section). So a reasonable strategy might be to ask, for each 
corner of the sprite, whether it lies on top of ihe other sprite. 
QuickTime 5 introduced a very useful operand for this, the 
kOperandSpriteTrackSprilelDAtPoim operand. This operand 
takes two parameters, which are the horizontal and vertical 
coordinates of a point; it returns the ID of the topmost sprite 
at that point; if any. 

In the case where we have just two sprites that can collide, 
wc need to attach the collision logic to only one of the sprites. 
That sprite (let's call it the collider) can check, on every idle 
event, whether any of its four comers has come into contact 
with any part of the other sprite. That is, well call 
kOperundSpriteTrackSpritelDArPoint four times, each time 
passing one of the fou r comers of the collider. QTWi red Actions 
uses the QTWired_AddCol 1 isionLogicToSprile function (defined 
in Listing 10) to attach the collision logic to the collider 


Listing 10: Wring a sprite for collisions 

QI ’NS m\\ _ U kKo 11 Hiti y&c TuSp rite 

G$fi t r QTW i red_Arf dCo11isionLogicToSprite 

(CfTAtomContainer theSpriU?) 


[ 


OSErr 


myhrr - nuErr: 


royErr “ (nVired^AddCornerColliisionLogicToSpriteltheSprite. 

kOperandSpriieBquudsLeft, kOperaodSpritrBoundsTop); 

If (myErr 1= noErr) 
goto bail; 


ctyErr = (TrWiredJkldGornfirConiBioiiLogicToSpriteitheSpritG, 
kOperandSpriteBoundsRight. kOperandSpriteBoundsTop); 
if CmyErr != noErr) 
goto bail; 


myErr “ QTWired^ AddCornerCollisionLogicTaSpritC! (thpSprite, 
kOperandSpriteBoundsLeft, kOperaridSpriteBoimdsiioUon]); 
if (myErr I- noErr] 
goto bail; 


myErr - QTWired_AddCoraetCollisionLogicToSprite{t heS p rit e, 
kOperandSpriteBoundsRight. kOperanclSprlteBoundsBottom); 


bail i 

return(myErr); 

\ 


We won't Ixjdier to dissect 

Q"Wired_AddComerCollisk>nLogicTo$prite 1 as it masLly covers 
routine ground while setting a new necord for length (almost 300 
lines of code and comments). The key step is using 
kOpenmdSpriteTrackSpritdDAtPoint, as described above. You 
should know that kOperandSpriteTrackSpritelDAlPoint does its 
work by hit-testing for sprites in the sprite track (probably using 
SpriteMediaHkTestAllSprites, which we used in an earlier article). So 
a sprite ID will Ixr returned as the operand s value only if some non¬ 
transparent part of a sprite is situated at the specified point. 

Our collision logic as developed vo far is pretty good, bur alas 
not perfect. Recall that we are testing each of the four corners of the 


> iNTERNATtONAUZATtON 4 LOCALIZATION 


la i 2 A 121 m iti m iu n? tie to* im to* u; i« «« w h it 



Hi root ion International 
CJ I I Ks\~s L I \J I I Software Solutions 

Intrigued by global opportunities but not sure how to get there? if you 
are venturing into international markets for the first time, or updating 
a previous version ol your sol I ware, we can help you gel to markel 
quickly with a fully localized product. Geotopia offers a broad range 
of internationalization and localization services supporting all aspects 
of your product! customizable to meet your exact needs. Call us 
today for a free consultation. 

f£U 800.553.2275 \ 801.796.2124 WEfi: wwir.^otopiaxom 

geotopia™ 


76 


QuickTime TooiKrr 


Ma<Ti-:ch • July 2(X)1 


























collider sprite’s lx binding rectangle, to see if ii lies on top of some 
sprite. If rhe collider's sprite image at tliat comer Ls non-transpamnt, 
tlien i lie coll to kOperandSpriteTrackSpritelDAtPoint will always 
return a non zero value (since the sprite hit test will find that comer, 
even if the other sprite Ls nowhere near the collider). We can solve 
this problem by ensuring dial the other sprite has a lower layer 
property than the collider (so that we get its ID if the other sprite 
and the collider overlap at rhe tested point) and by ignoring the 
collider's ID it kOperaiidSpriteTrackSpriielDAtPoint returns it to us. 

Another problem arises if the colliders sprite image Ls 
transparent at a corner whose coordinates are passed to 
kOpeiandSpriteTrackSpritcTDAlPoint. In this case, it's possible for 
that corner to lie on top of a non-transparent part of the other sprite 
and lienee trigger a hit, even though the sprites do not appear to lx.* 
touching. Figure 10 illustrates this possibility. In tills case, the 
collider is the Top-right sprite, and its lower-left comer is transparent. 
kOjXTandSpriLeTnickSpritelDAlPolrit will return the ID of the other 
sprite, because the collider s lower left comer does in fact lie on top 
of a non-transparent pixel of die other sprite. 



Figure 10 Testing a t rati spa rent corner 
of the collider sprite 

I don’t see an easy way to solve tills problem, but all in all it’s 
a fairly minor one. For most purposes, I suspect, it's gcxxl enough 
to have the sprites recoil from one anolher using the simple wiring 
we've developed here. More complex collision algorithms are of 
course left as exercises for the reader. 

CONCLUSION 

In diis ank le, we’ve seen how to add wiring to text tracks and 
we’ve investigated a few of the text-related actions and operands 
added in QuickTime T We’ve also touched briefly on the new key 
event (of type kQTE went Key) and seen for the first time the 
technique for retrieving event parameters. Finally, we’ve added 
some wiring to allow sprites to collide with the track rectangle and 
with one another. 

With all of this, we’ve reached the end of our “mini-series* on 
sprites and wired actions. We ll revisit them in the future, however, 
especially w hen we learn how to work with QuickTime VR movies 
and Flash tracks. In the next article, though, well shift gears and 
move on to consider some new and exciting QuickTime capabilities. 

Credits 

Thanks are due to Bill Wright for clarifying some issues 
with text wiring. CSTJ 


July 2001 * MacTkch 


Mac OS X 

R ® T a 1 am « I * | * H M j * V i ¥ 1 IT a I e] | |T n \ JR 

ImUKl I [Ii i I ' u \ i' 

KiMMlM 

Mac OS X 

Making the Move 


with MJ£ f£ :< now HRWltt 
Mac developer^ everywhere have a 
major need for C AR B ON and 
application porting, user interface 

implementation, and OfUilfl development 
services. Toward that end. several 
high-quality S^T 1521 !^§ engineering 
firms, in association with the 0 PPLII 
DEVELOPER EONNECliON. are offering these 
services at very allraclJue discounts 
to all A,IX Select and Premier members. 


The following pages 
are those vendors that 
are part of the Mac OS X 
Porting & Development Showcase. 










use mm: pcmcja swim tcp/ip m ldap Nuimfo Mw*m Bridge pcicatu; basic mm p icu 

10 Kll XEXT Curium Cl«slf :w Gt>|nc|lflt C Java BSD Mu n Km nvl Aq-i ULMrt/ Apr SI XML Gukkrtma 
VWflo OJQitittt DloltaJ Caraewa wet. M&iirm Sfnflititg P/lrSvT Driven A ilL-i t M‘'J Piuyan Sound Mi" 
Dlgtlal Audio Movie? Import USB FiruWire PCMCIA Sanat 1CP/IF SMB AFP {ME WMHi.v Mndomt Brians PCI 
Caida BASIC SUmo Pic II 10 KEG Caroon Ckt;; Sou (Mneiva': Ja*n BSD Math XatKU! Aqus (lunitt 
Open 61 XML UiiicWiHVP VWw.Diuititm 01 q|I*I Camara* Wat) Album- Stfurnwg Pit bn I’Mvtfi & U!lll Ilfs MP3 
p:a*#n Sound Mifiagm Digit* Audio Vovka fmag«s USB nnWim PCMCIA r*Ui»' TCP,IF SMB AFP lDAP 
Neiirtfo Modem* Bridges PCi Card; BASIC Stamp Ptcll 10 Km Kf XT w&on Clime Coca Oftrecftm C Jiv* HI " 
Mach Kernel Aqui Quart* [JmGi XMl LLuicAT in* Video Dipiiuni n uitiI Camera! wat» Aibir’*; breaming PriMl*' 
DfiWfiri A UtlllUti MFSPt***n Sciiifd Misi«goT JigltH Audio Mirim frttaytnp USB fireWiie r:.MCiA Serial TCP/IT 
SMI* AFP loaf Hafinru Mutest* Bridges PCI Caidi BASIC 5Um» Pk II ID Kit KIXi Citom Cltism Coc* 
nnietfi^ C Ja« 350 Mica fawn Apa Qsiim Q\w 6L XML Qo tiT»mp Video OIpJtlLm igilit Cam™ With 
Albums Strtiming Piinrii Drivtm & iJtiMms MP3 Player* Sound Vanin#' Digital Audi" Woviet 1/nsgfj USB 
mmt PCMCIA 5*i‘if rCPAP sm AFF UJAP HHIfte Mudema BfHsJfli PCI Catto BASIC Slims Pis t! tQ Kll 
KIXT Carom* Classic Cota 0h|»ciiva C mi BSf V.wi» Astro I Aqua Ouartj Open 01 XML QuickTime VHled 
Diailtm Dtoitit Camerii win Album* sueumlng Polite* Dturtra A UHium MP3 Pityan $s>tmc Murage* Digital 
Audio Mavlim Image* USB ftrirWir^ PCMCIA Sem ! fCF/lP SMB AFF HAP Mill Mo Mortem* Btldgti PCI Carat 
BASIC Slirnti Plcll *0 KM KfXt tUufcw Classm Ces£ Qbfttlum k hta 05 P Mach Kurnal Aip?a Guam Open 81 
XML OuiL'iTiint Vidfld 0iP»gliil C»m«M» WMi AibiM*ni Prmtoi BMfWr A Ullilfisi MP3 Pfanni 

Sound Mi mtt Dfgilti Autl'iu Muim Irtraus^ F«r»Wlrfl PCMCIA Sanai L.P/IP SMB L0AP Mutlr , 
ModiMOl U.uiDdi PCJ CittfS BASIC samp Pic n iu Kll KEXT LarDtwi Clastic Citca ODjRCtivu i .iiVM BSD Micr 
Kfiiwi Aqta Quirti Open Gt XML Otii^Tinie Vidoo OigiK/ar DlQllal Owmi Who Amu in ? Sinaimmg PfifiWf 
DtJvbh I UlllHiaa MPA Playri ScuAif Mannflu Oiuil* Agtfto M&iJaa lm«ut^ USil FluWItO PCMCIA Smiai TCP/iP 
SMB AFP LDAP aullnfo Wadama Britfoni PCI QutU BASIC Bmw PiftH JO All KEXT C*Ucil Cl um=c Coca 
Q&isclive C Javi BSD MaotlKuriMl Ain,* Qmm Opisn C. XML QuickTInin Vldau Ulultlur Oigltif Camaia* Wob 
USB HiftWIrt PCMCIA Seiial TQp/ip 5MB AFP 10AP WtiUok Modni,*, PCI Cards m 1C Stamp ?k\\ 

10 Kir KW Cadnorr Cla$aic Coc* D1>i*cllv* C Java BSD Mtsiti Kernel Aqua Oiimt Opto GL XML Ouitirime 
Vidttfl Digmflf UlDtUti Cantoris Woo Allmmj Slittmliig Prlfllff Otltarn A UtlllliAf MP3 PHiynis Sfltmd Miriagar 
uigiiai Aumo Mnvits images US» ritWim PCMCIA Smut! FCP/tl* CMS AFP LD^ WMSiiSw Mud^m* Qiidgat 'Cl 
Cams BASIC Stamp Pic It 10 Kir KEXT Carbon Ciacsic Cnt# Dbjadnre C Jim BSD Mach XafMl Aqirn Ouam 
Otxm &L XMl OtiirkTimf Vldio Oiufiirat Digital Cainraa Web Aihunu Strairnmo P"nt*T Binrnrs 5 UHJltma MP3 
PUvara Sound V.may*i DiQllal Autlut Md^Jea Imigru 0$fl HmiAiie PCMCIA S«nil TCP/IP SMB AFP LDAP 
Noltnlc Mud litt® BJidgea PCJ C«tds 0ALUC 31amp Pic n 10 KU i<£XT Caibon Cttit Coca Gfijitt(n> C Jrm BSD 
Math Ketnul Agui Quiftr Open LL XML QuickTime Video OI§l Diu Digital Canwa?. wnbAUnrms Streaming Pit runt 
Qrwsit & Ulslilles MP3 PtflfVfi Soumt Manag« Digdal Audio Mooiw Imagea USB F|? c iv .« PCMCIA Sitlal TCP/IP 
SMB AFP LOAP Hftlnlo Madams Brtdfler PCI Cards BASIC Stung Pic 11 JO Kll Kfxr tubo* CteftCic Cuts 
DhjadJveC Java BSD Maeti K«tm 1 Aqui Q ■ U Ggtn EtL XML Qvickllmi Vldao Olym/a» ^jital C«mir*L a 
A lbums Stiamina tVniin Dtlmrs %. Ullibtra MP3 Players Smmd Mitiijat DhjBal Audio hnavn USB 

RraWrrt PCMCIA SaMai ICP/IP SMB AFP UJAF Kwlirhi Modnms Bridge PCI Cardt BASIC 3:imp Pic II 10 KB 
HEAT Car bun Ctaulo Coca Qbjrtilve C Java BSD Mach Kama! Aqta j mU Opsrt Gl XML QuickTime Vltlsj 
OiflilUar Digital CarrmrDa Wil> Albums Strear^rng Pirntw Drlwi A MP3 Platan 3 nurtd Meager Digit a' 

Audio Movies images USB FlfiWln PCMCIA SwUI TCP/IP SMB AFP LDAP Kotlhto Mndams Bnagaa PCI Carte 
BASIC Stting Pit II 10 KH KEXT Carbon CiasaEt coca Objadiw C Java BSD Mach Kernel Aqua Quirti OganSl 
XML QuickTime Video Dlg-tuar Digtlai C*me<^ w*t? Album SirramiiHJ Prrw*e Dflww A *IM 'i« MP3 Ptavnra 










We consider the factors and provide results. 

Sixteen years of experience coupled with the resources and flexibility you need. It's no surprise that our 
achievements are integrated into many of the products you and your customers have come to rely on every 
day,.. do the mat! . Prosoft Engineering, Inc, offers unsurpassed advantages including professional engineers 
with in-depth knowledge of OS X, partnerships with the top industry leaders, and corporate headquarters located 
in the heart of Silicon Valley. Prosoft Engineering, Inc., is your source for cost-effective, on-time, custom 
cross-platform software solutions and services. By uniquely integrating Software Engineering, Quality Assurance, 
and Project Management, we offer you the solution you need. it ail odds up. 

(925} 426-6100 * www.prosofteng.com * mfo@pmsofteng.com 


PROSOFT 

engineering inc. 









EXPERTS CAN 

INTERPRET SIGNS. 


ra 11 p I soft ware 


When something unusual occurs, it rates 
thoughtful advisors to interpret meaning and 
impact. Moving your software up to Mac OS X? 
It's not your usual migration -so you need an 
expert guide who knows how to get you upgraded 
without getting lost. As the Midwest's largest 
Apple* developer. Parallel is the OS X transition 
expert. Well give uncommon insight to your 
application planning, development, and 
successful migration. 

Fly by our White Paper, Mac OSX Migration at 
www.paralld.coin 

Call us at 877-PARAIJivL 

n jhI r*rtlH s«jft»TWf AppV h m n*^ai««* tratmirtc rcmiwtec 












We Have the best engineers around. 
If it's Mac , we've done it. 


15 Year Track Record of Delivering Consistent Customer Satisfaction 
Highly Skilled Quality Assurance & Testing Team 
* Development Centers Nationwide 

a Over 175 Engineers VANTEON' 


Extensive Configuration Testing Facilities 


Delivering Innovative Engineering Solutions 


For more information please call 1-800-266-5046, e-mail at mac@vanteon.com or visit us at www.vanteon.com 








Eat your vegetables. 

D Exercise every day. 

(sJ Port to Mac OS X. 

□ Call your mom. 

All of these are good for you. 
We can make one of them easy. ! 


Since J 989, The Omni Group has worked with the technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That's been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's FrameMaker to NEXTSTEP and Sun's Concurrence to OpenStep/Solaris. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported idfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We’ve written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


The Omni Group 



2707 Northeast Blakeley Street 
Seattle, Wash ington 98105-3118 
www.omn i group.com/consulting 



satesfomnigroup.com 
800.315.0MN1 >c201 
206.523.4152 x201 


MflfflSV si Visit ] 1 pi tiSbp 4 tv ir.hkm.irto nl Apple. and 1-nuneMbUr lire- irwdc marks of sdi*. SytiemA liu. aikl itotm iradeotuU -d Id Software. NMarh Mitt OmnmmsL 

Nun M kivwynrm*. Or* k tv a irhdemark ofot-arkr. LiSdt and Vmidi h,, jjv tradeuui 1 4 <df v "1 U- Omni flitiujt" OmthWeb t . and I he Omni Unt 1 Jit ottra. IVstscdonT six? us. And ctidl v .w Ptoi 




























Without sufficient resources or the right expertise, your project is at risk of shipping late. 
Atimi guarantees reliable and timely Macintosh software development. You get to market 
on schedule-and to the satisfaction of both you and your customer. With a wide array 
of technical expertise, Atimi offers a full range of services: 

Classic Mac OS to Mac OS X application porting (Carbon and Cocoa) Windows to 
Mac OS application porting [ Application development Driver development 
(printer, PostScript, USB, Firewire, etc.) Networking development (wireless and wireline) 

Contact us now and learn more about how Atimi can help you with your project 

Call 604.813,1319 or visit us at www.atimi.com. 




Software development On-time. 

* 200i r Alim, Software Inc. Ail right* revme AHmt is i mdcmaifc of Aftmi Software Inc. 
AS other trademarks are the properly qf ibeit respective owner* 









CARBON 


By Ed Voas, Apple Computer, Inc. 


Introduction to Carbon Events 


The basic concepts, terms, and philosophy 
of the Carlton Event Model 

Introduction 

Without question, the single most important advent in 
the history of the Mac OS Toolbox is the Carbon Event Model 
(CEM), What the heck is that?" you ask. It is your new best 
friend. It will make it possible for you to write an application 
in a lot less time, and make your code cleaner and more 
consistent, Ji also allows you to tap into the code flow of the 
Toolbox without patching, and allows Apple to implement 
new functionality without many undesired side effects. This 
article gives a high level overview of the terminology and 
structure of the CEM, and hopefully will demonstrate the 
power and ease of use it can bring to your applications. 

Overview 

The CEM is the underlying event model for Carlxm, li tis means 
that classic Toolbox Event Manager routines like WaitNextEvent are 
built on top of this new model. When calling WaitNextEvent, native 
Carbon Events are converted info EventRecord structures so your 
application can deal with diem as it always has. 

Bui of course, this new model does much more than serve 
as a mere foundation for WaitNextEvent — it also exposes a new 
way of receiving events in your application. Instead of looping 
around to pick up an event, deciding where it goes and 
dispatching it yourself, you can instead rely on tire Ttxdbox to 
do this for you. Also, Carbon Events are much more expressive 
and expandable than the classic EventRecord structure, This 
means Apple can add more information to events as the Toolbox 
evolves. 

An important point to note is that this event model isn’t just 
picking up events and doing something with them, but rather it's 
a whole new inter-object messaging infrastructure. Every 
component in the Human Interface Toolbox (HIToolbox) ties 
into Carbon Events somehow. It's quite pervasive. 


Another key tiling is that the CEM is not something ihat needs 
to lie adopted all at once. Existing applications can adopt it in stages. 
We recommend new applications use Carbon Events from the start, 
as it saves a lot of coding lime, I think that once you see what it can 
do, you’ll want to start using it right away (waves hand ala Jedi). 

Model Building 

There were several compelling reasons to invent a 
new model. 

First, we wanted it to lx:* incredibly simple to write a Carbon 
application. Most of a basic application involves receiving and 
delivering events to the appropriate place and handling them with 
old standbys. For example, what do you do when you receive a 
click? Typically, you call FindWindow to find out what object was hit 
by the mouse (window or menu liar). If the click is in the menu Ixtr, 
you call MenuSelect and act on the result. If the dick is in a title bar 
of a window, you might call DragWindow to move the window 
around With CEM, all this default logic is now in the Toolbox, so 
you don’t have to write it anymore. Good. It was a pain anyway. 

Second, we wanted to promoLe an API that encouraged 
good performance, especially on Mac OS X. Many applications 
written for past Mat* OS releases have used programming idioms 
and APIs that worked fine on Lliosc releases. On Mac OS X, 
however, they actually work against the system. For example, 
simple mouse tracking loops will take up close to 100% of the 
CPU on Mac OS X. With new APIs Lo replace those tracking 
loops, the CPU usage in these cases is next to zero. 

Third, we have a multitude of messaging models in the 
Toollxix. We have callbacks, control definitions, window definitions, 
list definitions, menu definitions, events, and Apple Events. The goal 
of the CF.M is to unify almost all of these into one consistent model. 
Once you learn it, you know alt you need to know in order to listen 
for new* events in the future. Carbon Events subsume everything 
except Apple Events, which remain the de facto interprocess 
eoi.nmunieatif m medium. 

Fourth, the old EventRecord structure was too limiting. Because* 
of that structure, plus the fad tliat an event mask was only 16 bits 


Ed Voas is the principal architect and developer of Carbon Events, He is also the Manager/Tech Lead of the Carbon High Level Toolbox. When not 
coding, he is usually practicing Shotokan Karate or attempting to climb a solid 5,5, He can lx: reached at voas@applc.com. Maybe. 
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wide, we knew we needed a new transport far events. We needed 
something that would lx* able to carry hundreds or thousands of 
event kinds with plenty of room to grow. 

Lastly, this new model supports plug-ins better. Because we can 
directly dispatch events to windows, controls, and menus, a plug-in 
can actually get its events directly without neevssarily relying on the 
hast application to hand the events to it. 

EventRefs: Opaque and Loving hi 

I he basic: building block of tlie CHM is the EventRef EventRefs 
are opaque (virtually all Toolbox entities that end in -Ref arc 
opaque), To get at irtfbrrrmtion contained within an event, you must 
call accessor functions, For example, to find out when an event 
ocmrred, y< ai would call GetEventTime, fWe pride ourselves on our 
original API names. ) An event is specified by its class and kind. For 
example, a mouse down event has a class of kEventClassMouse. and 
a kind of kEventMouseDown (Man, were clever!). ’Ihere are a ton of 
new event types defined in the CEM, many more than you've ever 
seen lx 1 fore on Mac OS. 

There are two iy[x\s of information in an event — information 
common to all events (such as class, kind, and lime), and 
infonnation specific to a particular event or family of events (such as 
mouse button, or keyboard modifiers). This type of infonnation is 
what we tenn pammHers of an event. They are accessed via the 
SetEventParameter and GetEventParameter APIs (how do we think 
these up?). Parameters are merely generic I dobs of data that can be 
attached to an event. You access them by symbolic names such as 
kEventParamMouseLocation. The type of data stored in the parameter 
is represented by a constant such as typeGDPoint, Por those familiar 
with Apple Events, this will seem very similar. Well. . OK. identical! 

Tlie advantage of this parameterized methcxl is that we tan add 
any number of parameters to any event. We tan also do this at any 
time, meaning that in later versions of Carton, we can add new' 
parameters to the mouse down event without affecting existing 
applications, We can even start to store information as different types 
and automatically coerce them to the original type for existing 
clients. That's a powerful advantage of opaque types and generic 
parameter APIs. We dure sty they rock. 

One other note about events in the New World of Carbon: 
events are not necessarily one-way. They are also used for two-way 
communication between objects in the Toolbox. You can ask 
questions of objects anti gel responses which gel stored as 
parameters. You do this by sending events directly to objects instead 
of posting them to the event queue. 

limes in an EventKef are expressed differently than in die past 
as well. In an EventRecorel, tlie when field yielded the time since 
IxmH in ticks (via a call to TtckCount), EventKef times are also time 
since Ixxit, but given in seconds as a floating fxmu number. So 
fifteen and a half seconds after lxx>t is, incredulously, 15.5. Tlie 
replacement for TickCount wlien dealing with EventRefs is 
GetCunrentEventTime. There are macros in the headers dial allow you 
to convert between ticks and the new EventTime type. 


The Event Qi^eue 

When events come into an application, tltcy are turned into 
EventRefs and posted onto tlie application's event queue. There they 
wail until the application calls an Event Manager API like 
WaitNextEvent to fetch them 

Tlie event queue is a little different under Carton than under 
traditional Mac OS. First, like EventRefs, it is an opaque entity. You 
cannot directly walk it like you could under traditional Mac OS. 
Because of this, there Ls a complete set of routines to allow you to 
past, search for, and flush events from the event queue. 

Hie event queue Ls also per-process under Carlton, not global 
as it is in traditional Mac OS. This means you cannot jx*ek at events 
destined for olher prexcsscs, nor can you |xist events for other 
processes to receive (except, of course, Apple Events) 

There can actually be more than one event queue in your 
application. The main thread and all cooperative threads share one 
event queue, which we call the main event queue. Any MPTaxks that 
you might create in your application geL their own event queue, This 
is quite handy if you wish to use Carton Events as an inter-thread 
communication medium. 

T he Event Loop 

I mentioned atove that events come into an application and get 
turned into EventRefs. Well, the Event hoop i.s what takes care of 
that. When the Event l.cx>p i.s ‘mri, it waits for events and converts 
any that show up into EventRefs and jxxsts them to the event queue. 
Typically, the Event Loop is run for you inside tails like EventAvail 
or WaitNexlEvent, 

The Event Ixxrp Ls also where your application will block while 
waiting for an event. U essentially puts your application to sleep until 
an event (mouse dick, Apple Event, etc.) comes into your 
application, You cm think of ihe Event Lcx>p as a condition variable 
(for tho.se familiar wills such constructs) which you wait on until 
some event arrives. There s some other stuff that goes on inside here, 
but well cover that later. 

II is important to know atoul tlie Event Loop and how it works, 
since it means dial there are only certain times the Event t.<x>p Ls run 
and events get into your application, if you never run the Event 
loop* your event queue w ill always to empty! 

For every 1 Carton event queue, there is a corresponding Event 
Loop that is tied to it- With that in mind, like the event queue, the 
main thread and all cooperative threads share the 'main* Event Loop. 
Mfftasks have their own event kxip. 

1FW, Fin going to tell you now iliat the Event bx)p term Ls 
going to confuse you. It was not tlie I jest choice of names, but 1 
couldn't think of anything I setter at the time, 

Event Handlers 

For anyone who lias used Apple Events, Carton Event handlers 
will seem pretty familiar in form and function, with some 
improvements. These handlers are the means in which your 
application receives events. You install them by calling 
JnstaJEventHandler You can install handlers onto windows, controls, 
menus, and the application. The application is a root-level place 
where events go if not handled by any other handlers. 
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1 wan t get into where it's \ycst to liancile certain events here. 
That's beyond die scope of this article and best suited for another, 
more in-depth one. We call that ‘job security.“ 

You install an event handler by calling Install Event Handler: 

InstallEventEandler£ 

EventTargetKef inTargei. 

KventHandlerUPP inHandl e rP roc, 

UT nt 32 iaNunEvent s, 

const EvcntTypeRpec* ItfEventList, 

Void * i nttse rData, 

EventHandlerKeF outHandlerRef ): 

As you can see from the InstallEventHandler prototype, you don't 
actually install handlers onto windows and the like directly. Instead, 
handlers can only lx? installed onto Fixmt Targets. An event target is 
quite simply something that can receive events. To install a handler 
onto a window then, you actually need to get its event target. For 
example: 

InstallEventflanriler( GettfindowEvetitTarget{window}. )i 

One other thing you'll notice about InstallEventHandler is that it 
takes an event count and event list in the inNumEvents and 
inEventUst parameters. This is how you tell the Tcx)llx)x what events 
your handler is interested in. Keep in mind that a) you only will 
receive events you have registered for and l>) you ami receive 
events that don't make sense to be delivered to a specific target. 
What that means is that if you have a control in a window, and you 
insLall an event handler on it that registers for the 
kEventWindowUpdate event, it will never receive it since those events 
are always destined Ibr windows. 

The EventTypeSpec structure used to sjxeify events in the 
inEventUst parameter is a simple structure defined thusly: 

struct EventTypeSpec 
I 

UXiti 32 cventClHKFi: 

Iilnt32 ovcntKIwb 
(i 

The canonical way to define your event lisi and call 
InstallEventHandler is: 

const EventTypeSp*c kEveriLslJ * 

( 

{ kEventClassCocmand. kEvmCoiiinandlJpdaleStatys I. 
t kEventClassCoraand f kEventCoomiandPirgcesa 3 

U 

InstallEventHandler( GetAppl1 rationEventTarget(). 

MyEventJ Umd1e t UP?, Get EventTy peCoun t f kEven t s ). 
kEvents. iwUserData. tendler ): 

This registers MyEventHandlerUPP to receive two events. I he 
events in this example are command events, which correspond to 
menu selections. We won't discuss these" in this article (rememlxr- 
job security ), but in time you'll see that ihey’re a very powerful way 
of dealing w ith menu items and menu selections under the CEM, 
Well. dial's all line and dandy, but what does an event handler 
actually look like? The prototype for an event handler kx)ks like tliis: 

OSStatLts MyEventMandler C EventHandlerCsllHef iuCallRcf. 

Ev antRet inHvent. 

void * inUserBaia ): 


Well discuss the inCallRef parameter later, but essentially 
your handler receives an event and the user data you passed 
into InstallEventHandler, You should return an appropriate 
OS Status as the fund it hi result. This controls how r events 
propagate, as we'll see shortly. 

Events get to your handlers by means of the Toolbox 
dispatcher. This entity is c alled for you when you are fetching events 
via WartNextEvent or RunApplicationEventLoop (described later). The 
dispatcher decides where events should go and routes the event to 
the appropriate entity. 

Stack 'Em Up 

When handlers am installed, they art- actually pushed onto a 
stack for an Event Taigct you specify. When an event is sent to ihai 
target the event always goes to the top event handler on die stack. 
If that handier does not handle* the event, it then falls to the next one 
and so on through all the handlers installed on the target in the 
reverse order in w hich they were installed. 

Tliis stacked Ixdwvior allows your application to override 
standard Toolbox behaviors. One of the tilings you can do with the 
CEM is create a window with a standard Toolbox event handler 
attached to it. Such a window directly receives events fur dicks 
within its surface, and will automatically handle dragging, clicking 
the widgets, as well as tracking any controls that are in it. Some of 
its l>ehaviors are pretty txisic. though. For example, when we handle 
the close box Ixing hit, we dispose the window. In practice, your 
application might want lo do a bit more than that, installing an event 
handler pushes a handler on top of the standard handler, allowing 
your application axle to see the event first. 

When your handler sees the event, it can choose to handle an 
event or not. You can also call through to have any handlers befow 
you do their thing first and then post-process the event. You control 
this by tw f o mechanisms — implicit and explicit propagation. 

Implicit propagation Ls the natural order of tilings. In this 
situation, event propagation is controlled via the result code of your 
handler If your handler returns any other error but 
eventNolHandledErr, it is assumed your handler has either handled 
the event, or tried to handle it but encountered an error. A 
completely successful handler would return noErr, ['or any result 
other than eventNotHandledErr, event processing for rhe current 
event will stop light after your handler returns. 

On the other hand, if your handler returns eventNotHandledErr, 
the event will lx? propagated onto the next handler in the stack for 
the current target, ft is certainly possible for an event to not lx? 
handled at all by any handier. Tliis is fxrfcclly OK, and sumelimes 
actually desirable. Here is an example of a typical event handler: 

Listing 1: Typical event handler 

OSStJitue MyEventHandlert EventHandlecCalllk*f InCallRef, 

EventRef inEvent, 
void * inlJaerData ) 

I 

OKStatus resu}l ^ gupntRotHandledHrr: 

UInt Tl LheClass. thHUnd; 

WindowRef window = {WindowRef JinUserBata; 

theCIaKS = GetEventCAass( InEvent }: 

thoKind - GotEventKind( inEvent ); 
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If £ theClass “ kEventClassWiridow 
theKind kEven rWind ovD ravConrem: ) 

I 

DrawMyContent( window ): 

Result * noErr; 

I 

return result; 

I 


As you can see from the first line in the function, we always 
assume we didn't handle the event. That is the ItesL assumption to 
make. You .should only indicate you actually handled an event If you 
really, honestly, truly handled the event. If you say you handled an 
event, but you really didn’t, you'll feel really guilty later, and you’ll 
ix j subject to the rules of Karma. In the example above, if we 
received our draw content event, we set result to noErr, indicating 
we handled the event, 

'Phene are times, though, that you want to have the system 
handlers deal with die event first, and then you can follow up with 
some neat postlude to the standard behavior This is where explicit 
propagation conies into play. In this situation, you want to force 
handlers Ixduw your lumdler to lx* called immediately, and then do 
your follow-Lip work. You do tills via die Call Next Event Handler API. 
When your handler receives an event, you would call through with 
ihis API and then do your Lhing, Typically, you should make sure 
dial CallNextEventHandler returns noErr (indicating it handled the 
event) before doing any post-processing. Your handler should also 
return whatever CallNextEventHandler returned lor concctness. 
Hero’s an example: 

listing 2: (ailing through 

OSStanus MyEventKandler( EventllandlerCaliRef inCallRcf\ 

EventRei inEvent* 
void ‘ inllfierData J 

1 

OSSiatua rf^nilt *= pventNotHandledErr: 

bint 32 the&its#, theKind; 

theCiass = Ce tEveti (.Class ( itiEvent h 

theKind » GetEventKintM inEvent ); 

If £ theClass " kEven tCia e sContro 1 ink, 
thaKInd = kEventControlDraw ) 

I 

result “ Ca 11 NextEventHatid ler£ 

inCallRef. inEvent ); 

if £ result = noErr ) 

t 

// draw 'handles '<jii die couinjl, whkh 
// the uxt can manipulate to resize, (bag, etc 

MyDrawCoittrol Handles ( inEvent ); 

I 

I 

return result: 

I 

Now you re .saying "Aha! Thai s what the call ref is foil" Yes t ifs 
.sLrictiy used when calling the next event handler, it is basically a Nob 
of data that helps the dispatcher keep track of where it is so it can 
properly call through. Notice that we only call our function if the 
event was handled (in this case indicating that the frame was 
actually drawn ). We also return the result of CallNextEventHandler, 


and don’t set the result ourselves. 'the event was handled, so why 
should we lie about if? like 1 said, you'd fuel really Irad about 
yourself if you did 

Target Flow 

If a target does not handle an event, where does the event 
go? Well, that depends. In tile general case, an event will flow 
from target to target until handled, based on certain mles 
imposed by the targets themselves. In general, an event might 
flow to a control, then it’s parent control, then eventually the 
window and then the application. There are some exceptions, 
but well leave those for some other time. 

Tliis target flow can lx useful, in that you can handle certain 
events at any level. For example, a mouse click on a control could 
lie handled at the control level, or possibly the window level The 
Toolbox actually uses this to its advantage, using one handler for 
basic control tracking at tlx window level, rather than manage many 
different handlers on every control in a window. 

Making It Ail Go 

When writing a Classic Mac OS application, you typically would 
call WaitNextEvent to, well, wait for events. Tills is [lie top of the 
application s event loop (not to lx confused with the Event Loop 
construct in tile CEM). WNE also yields time to other applications If 
there are no events waiting tbr your application, it is put to sleep 
until one arrives or the timeout you pass to WNF expires. 

In the CFjM, there is a similar routine — ReceiveNextEvent. This 
routine acts almost identically to WNH, The only real difference is 
that you can control whether you want to actually pull the event 
from the queue or not. it can also return any event in the event 
queue while WaitNextEvent ran only return the events it always has, 
not any of the new ones. While ReceiveNextEvent is a fine, glorious 
API t you'll probably never call it, except in special circumstances. 

Instead, to drive an app written purely to the CEM, your 
application would call RunApplicationEventLoop. This API drives your 
entire application, and it pulls events off the queue for you and 
dispatches [lie events to your handlers automatically. Once called, it 
does not exit until QuilApplicationEventLoop is called. Essentially all of 
your application code is run via your event handlers. 

From Theory To PRAcrta- 

Now that we’ve covered most of the basics, let's see what a 
hilly Qnbon Kveni-lxiscd application looks like. Thu simplest ca.se is 
to use Interface Builder nib files, so that’s what we ll base this on. 

listing 3: Basic nib-based Carbon application 

nc lude <Carbcn / Ca rbon ♦ h> 

int main(int arge. char* argv[]) 

l 

rERIbRef niMef; 

Windovftaf window: 

GSStatus err: 

// Create a Nib reference passing the run*' 

// uf (he nib file (without the nib exteiisiuo) 

H CrealeNibRdbence only strardra into the 

// application bundle. 
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err = CreateNibReferencetCFSTRt^main* 1 ). tnihRcf): 
require_rioerr{ err t CantGer.NihRef J; 

// Orarc lire nib reference is creatwi, sci ilk- 
// menu IwM.iinMcrtn is the name of the menu bar 
// Object Tilts name is set in hitertiieeBiiilder 
// when the nib is created, 

err = SetHenuBarFroinNib{nibRef, CFSTR("MilnMnnu"))t 
require_jioen:( err. CantSetHenuBar J; 

//Then create a window.MaifiWiixbw" is the name 
// of die window ohjccLThis name is set in 
// fnteHacrffcrildcr when the nib is created. 

tnr = CreateWindowFrqmiNib(nibRef> 

CFSTRf “MainWindow"). Sviridov): 
require_noerr{ err, CflntCrraaTeWindow )s 

//We citin'I need The nib reference anymore. 

D1 a p 0 soN i bR e Tereue t? (n ibRe f): 

//The window was created hidden so sIkpw it, 

ShowUindowt window ): 

// Cdl the event loop 

RtmApp 1 lost ionEv o ntLoop () ; 


work with RunApplicationEventLoop f taxed applications as well as 
WaitNextEverrt-tosed applications. It s all good. 

Timers nin at task level — they are not like low-level timer 
mechanisms which fixe asynchronously with respect to your main 
application flow. You can safety allocate memory and call the 
Ux)lix)x willy-nilly from an Event Loop Timer, They are syncliromms 
in nature, i.e. a timer cannot he interrupted by another timer on the 
same thread of execution. If you want true asynchronous behavior, 
you should probably use tin MPTask instead, but then you're limited 
in what you can do (for example, you uan'r call most of tile TqoIIxjx 
from an MPTask at present). 

Tuners are run when die Event Loop is run. 1 mentioned earlier 
that the Event Loop does some 'other stuff/ Tills Ls it. If you don't 
run your Event Lcx>p, your timers will never fire. Ibis means that 
timers aren’t necessarily a guaranteed heartbeat, but they are more 
than adequate for most periodic tasks. 

Timers are merely callbacks that you install via die 
JnstallEventLoopTimer APE 


GantCreatcWindow: 
CdntSptMcnuBart 
CaruCkuNibltef: 
teuirn errr 

1 


Well, that wasn't so tod, was it? Keep in mind that this 
application actually does stuff. It creates a menu bar and a simple 
window using nibs, shows the window anti runs the application 
event loop. J there it remains until the app is quii. While running, the 
app is hilly functional — the menus track and the window can to 
moved or resized, etc. If the user .selects quit from the file menu, the 
app will automatically terminate. Well see how that works in a short 
while. 

U you have not used Interface Builder tofore, you should start 
now. It does an absolutely awesome job of letting you lay out 
windows and menus. It supports all the latest Toolbox features, and 
replaces old-style resources with new-styie nib files, which are 
basically XML descriptions of Ttx>ltox III objects* One of the coolest 
features it has helps you cleal with Aqua TUG S[>ees — when you 
drag items around, little guide lines appear to help you know wliat 
the standard IltG spacing is Ixitween items. It’s rmlfy cool 

One other comment about the code above — please notice our 
use of the standard require macros, which make axle much more 
readable while tumbling exceptions. This style of error handling was 
written up a long time ago in Apple's fonner Deudtp magazine, and 
we now have these macros in our Universal Interlaces in 
Debuggings for everyone u> use. I highly recommend them, Consult 
the header for more details. 1 mention this because you’re going to 
see i! more and more in our sample code and project templates, so 
it's helpful to to 1 familiar wiih it 


Periodic Time 

RunApplicaiionFventljoop will block forever while it waits tor 
events. But if it does that, how will you get time to do periodic tasks 
in your application? Traditionally, applications have relied on null 
events returned by WaitNext Event to get such work done. Null events 
do not exist in the GEM - Event Ixx>p rimers are the replacement. 
If you adopt only one aspect of the GEM, it should to timers. They 


OSStatus InstailEventLoopTimerC 

EventLoopRef f nEvantliOop. 

EventTimerItit erva 1 1 n F i r qBc 1 ay, 

Evg ntTtmn rIn t c rvat lain!erval. 
KventTiOopTI me r'UPF inTimerProc. 

void 31 InTimerData, 

EventLoopTimetRet'* outTiraet J: 
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When installing a timer, you cm specify whether you want a 
periodic timer or a one-shot timer (meaning it fires only once). 
Passing a non-zero value in the inlnlerval parameter implies that the 
timer Ls periodic, and passing zero means it is one-shot 

Typically, a one-shot timer would be set lo fire some number 
of seconds into the future, (Otherwise, if you want to fire a timer 
one time immediately, why not just make a function call?) That is 
what the inFireDelay parameter is ton This parameter can also lie 
used with periodic timers. Basically, inFireDelay is the time interval 
to wait until we first fire the timer. Once we start to fire, it we have 
an interval, we will continue to fine ar the rate specified in the 
interval parameter. 

I he routine we tall when the timer fires looks like so: 
void Hylin^r(EventLoopTimexRef inTtaer, void ‘inUserData); 

The timer that fired is passed into inTimer and the data you 
passed in the inTimerData parameter in InstallEventLoopTimer is 
passed Lo your timer in the inllserData parameter. 

Inskle your timer prtx\ you can do whatever it is you need to, 
including removing the timer, or abetting it: 

OSSta tus RemoveEveniLoqpTimer( 

Event UK>pTi<m?r Ref inTimer ); 

QSStatus SetEventloopTi HerNex c FireTime( 

Event LoopT ime rRe f inTi&ve r. 

EverttTimer Interval inNextFlre ): 

RemoveEvenlLoopTimer does exactly what you'd expect, ii 
removes the timer and stops it from firing, Alier calling that API. the 
timer reference is now invalid and should no longer l>e used You 
need to remove one-shot timers as well as |x.*ri(xlic ones — even 
though they may only fire once, they do not remove themselves 
automatically. This is mostly because you might waul to reset the 
timer after it fires. 

SetEvenloopTimerNextFireTime lets you reset a timer. This is 
typically used fora one-shot timer. For example, lei’s say if the user 
doesn’t move the mouse in ihe next 10 seconds, you're going to quit 
your application (that’s just the way you are). You wottld install a 
one-shot timer with an inFireDelay of 10 seconds, and an interval of 
0. Each time the user moves the mouse, ytxi would reset the timer 
with SetEventLoopTmerNextFiretime, passing 10 into inNextFireTime. 
If the timer fires, you set your quit flag and remove the timer. 

You can also use SelEventLoopTimerNextFireTime with 
periodic timers if you wish, possibly postponing some sort of 
periodic action for a number of seconds. This API docs exactly 
what it says, it sets the next time the timer will lire. This applies 
to one-shot as well as periodic timers. If you have a timer which 
fires every second, and you set the next fire time to 10 seconds 
from now, the timer will lx* dormant for 10 seconds, and then 
start firing every second after that again. 

Performance On Mac OS X 

All this talk about rimers reminds me of performance Issues, 
particularly on Mac OS X. The goal which even' application 
should strive for on Mac OS X is to use 0% of the CPU when 
idle. That's right, zero. If your app is not foreground, there 


should be no activity. This has a substantial impact on overall 
system responsiveness and performance. This means that 100% 
of the CPU is available for meaningful tasks, such as 
downloading files, or rendering images. It also means that the 
VM working set is sul >shtmiaHy less, since we don't have to keep 
pages hot for applications in the background. If you are polling 
in the background, you are stealing resources from the 
foreground application* making things slower for quite possibly 
no good reason. 

Some people respond to this hy saying 14 Wait a second you 
crackpot, 1 thought Mac OS X was preemptively scheduled. It 
shouldn't mailer if I spin the processor,* While this is true, 
remember that we are all sharing the CPU on X, and if two apps 
are spinning as fast as they can, they will only get about 50% of 
the CPIThree app and you get 33%. 10 apps and you can now 
only I tope for 10% of the CPU. If nine of those apps are just 
checking to see if a file has appeared in some folder, and one is 
trying to do real work and download a file, your download will 
be 10 limes slower than it could be. That s pretty significant. Yes, 
even in this brave new world, we need to l>e good citizens. We 
can’t stop another process from running like we can in 
traditional Mac OS, but we can sure slow it down. 

Now, don’t get me wrong — there certainly are classes of 
application that must get idle time constantly: browsers displaying 
animated GIFs, clock applications, music players which display 
frequency meters, etc. The goal though is to not lake up any more 
idle time than is necessary, II you are displaying an animated GIF 
that displays each frame every second, then you only need a one 
second idle hearlfxjut in your application. It you are displaying no 
animated GIFs, you might not need any lime. The trick is to only get 
the time you absolutely need. 

Reaching this goal of zero CPU usage may seem impossible, 
but the ('EM goes a long way to help you reach that goal. We 
offer several means of accomplishing that — Timers, lierter 
tracking loops, and new events to notify you when certain things 
change. You’ll find that getting down to zero CPU usage is nor 
impossible at all. 

User Focus 

One concept we are introducing with the CEM Is that ot 
userfocus. Put simply, the user focus is the Event Target where 
keyboard events are sent. You can think of ii as the extension of 
the current keyboard focus concept in the Control Manager. 
Menu commands art 1 also sent to the user focus, but well look 
at those in the next section. 

The user focus is the combination of the current userfocids 
window and any currently focused control in that window. The user 
focus window is normally defined as the currently active document 
window, II no controls are focused in that window, the window Ls 
the current User Focus target, anti keystrokes are sent there. If there 
is a focused control in the window, the control is the current User 
FrxTis taigeU and ii receives keystrokes. 

When file user clicks on a document window, the Window 
Manager changes the user focus window to the newly selected 
window automatically. If the user dicks in a floating window, die 
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user fexus winctow ckx*s no! normally change. I towever, if the user 
clicks in an editable lexi held in the floating window (or any control 
that wants focus on mouse clicks), the Toolbox will switch the user 
fcx iLs to the floating window for you. Yes, the Toolbox makes the 
rash assumption that you’d like to let the user actually type into that 
swell text field you pul in your floating window, If the user dicks in 
the hfxly of another floater (but not in a ftxus-on-click controlX the 
user focus Ls reset to the currently active dexu merit window, 
likewise*, if the user c licks in the currently active window (or some 
other document window ) while a floater has ftxtis, the user ftxus is 
reset to the window that was clicked. 

It is possible' to alter where keystrokes go by either changing 
the keylxKtrd focus via the existing Control Manager APIs such as 
Advanc^KeyboardFocus, or by using the new SetUserFocusWindow 
API. This API tan divert focus away from die default of the active 
window. This Ls how the floating window behavior atove is 
implemented You can also reset die focus to the Tnoltox’s standard 
choice with SetUserFocusWindow by passing (WindowRef)-1L tor the 
window' ref you pass in. 

Commands 

Metiu commands have Ixen supported since Mac OS 8.0, 
Essentially, they represent a position-independent way of 
identifying menu items or menu selections. No matter where your 
menu item happens to be, the command ID is always constant, 
Carbon Events extends the concept of menu commands to include 
controls as well, both menus atid controls use Carton events to 
indicate that the user has manipulated file object. A menu selection 
or a click on a control will generate a Gtrton event of class 
kEventClassCommand and kind kEventCommandProcess containing 
the command ID associated witli the command. 

Ihe Carbon event manager packages the command ID 
generaied by a menu or control into a new object called an 
IHCommand. This structure contains information about the 
command, such as where it was generated from (menu and item 
nmnlxir), as well as the actual command ID. Currently, control 
infomiation is noi contained in this structure, but that will likely 
change in the future. The Tmlbox uses this to determine how lo 
propagate commands through the containment hierarchy. An 
1 nConumnd tliat was generated from a menu will get sent first to 
the menu it came from, and then to the user focus, and so on dow n 
the chain. An HJGommantl generated from a control merely struts at 
the control it came from and down the conutitimeni hierarchy as any 
other control event would. 

Commands are essential to a Carbon Event-based application. 
It is, in fact, a menu command that allows a standard Girbon Event- 
based app to quit. As long as the Quit menu item lias the standard 
menu command of kHICommandGuT your application will terminate 
normally. This is how the nib-leased example we looked at earlier 
quits, When the kHICommandGuit event is sent from the menu 
selection, it eventually reaches the standard application-level 
T(x)llx)x handler, where tlie T<x>llx?x responds by sending a 
kEventQuitApplication event to the application target. If the 
kEventQuitApplication event is not handled, the Toolbox receives iL in 
the same application-level Tcxiltox handler and call 


GuitApplicationEventLoop This terminates the call to 
RunApplicationEventLoop, and eventually exits the program. If you 
happen to lx a WaitNextEvenf application, you won't quit 
automatically, but you could intercept the command event w itli an 
application level event handler and trigger your normal quit process. 

Commands are also important for menu item enabling. 
Whenever a menu is about to lx* displayed, the Menu Manager 
attempts lo ensure each item is in tile correct state, i.e. it is enabled 
or disabled, lias the right text, anti so forth, It does this by sending 
kEventCommandUpdateStalus events to the current user focus for 
cadi item in the menu. This is the time for Lite user focus to examine 
its cuiicnt state and adjust its menu items as appropriate. For 
example, if the Kclit menu was about to lx* displayed, you might 
warn to enable the Cut and Copy menu items in your Edit menu if 
you have an active selection. If your application needs to change the 
name of the item (for example, to make the Undo item say “Undo 
Typing’'), you can do that at die same time. Essentially, you should 
make sure the menu item which corresponds to flu* command sent 
as part of die kEventCommandUpdateStatus event Ls set up correctly 
for display and selection by the user. 

Let's lcx>k at a small example of a handler that deals witli 
kEventCommandUpdateStatus events. 

Listing 4: A command status handler 

05Status 

KyComn.ind S t atutsHand 1 e r ( EventEandlerCallUrf UiCallRef, 

Event.Rnf inEvent, 

void * inlfserData ) 

t 

OSStatUS result * eveutNotHandledErr: 

HICommand and; 

HyObjact* object = (HyObject’JinUserData: 

//The dircet object for a command event Ls the NTCornnuiit! 

// Exxon it here and switch <»fT the command tn. 

CetEventParameter( inRvmrt, kRvenU'arHmDirectObject, 
typeHlCoromand. NFTI.T,, al^eofC cmd ). MOLL, ): 

// Only deal with mem* commands ]1xlbolLx>X will eventually send uptLiir sraha 
// events fur romml commands as well, so we should limn our scope to menus if 
// iliat s all wc eaiv about. 

if ( (crad. at tributes & kHTCoTimiandProtitHeTiul 1“ 0 ) 
t 

//YouTI note hekiw that wt* enable jrxl disable 
if by menu rvf and index rather than tht" command 
// llYlhis is because it Ls nxxv efficient to do 
// so, since aixx-ss by command It> requires die 
//Toolbox to search id! menus lather way is tine, 

// but 1 thought rd point that out. 

switch ( emd.commartdTD ) 

I 

case kHTCommandCopy; 
cane kHTCoimaatidCut: 

If [ object->HasSeiectioa{) ) 

I 

KnableMenuItecn ( cmd. menu. menuHef, 

c rad. menu, m v nul lemlTid ex ): 

I 

else 

I 

0 1 s nb1oMenu1tern( cmd,menu,menuke f. 

cmd.isenu.menuTfomIndex ); 

I 

result = noErr: 
break: 
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ease kHICommandUndo: 

if ( Object->CanUndo ) 

I 

RnahleHenuItein( cmd.nena.nicnuRcf, 

and. menu. menul l era! ndex ) ; 

SetHenu t1 cufText ( cmd * m&nu . memiRef * 

and,menu.menu 1 remindex♦ 
ob j ect - >GetOndol)tring ) i 

I 

else 

l 

D S nabieMenuItem ( ctnd. menu.tnenuRof * 

cmd♦menu - menu l Lem T ndex ); 

Se iMenuItcmText( cmd *menu.menuRef * 

ctad.menu.menuItemiudex. 

CFSTR( "Can't Undo" } ); 

\ 

result - noRrt: 

break: 

I 

] 

return result: 

I 

As you can see from the listing, wc lcx>k for tile cut, copy, and 
undo commands in our handler For cut and copy, we merely 
enable or disable the menu item depending on whether our object 
lias a selection. For the undo command, not only do we enable or 
disable the item, but we also change the text of the menu item as 
appropriate. In each case, we return noErr to let the event system 
know this handler handled the event. 

This very mechanism allows the editable text controls in the 
Toollxjx to update the Edit menu appropriately depending on the 
current selection. For tills reason, it is important that the Edit menu 
in your application uses the standard cut, copy, paste, etc, 
commands that are currently defined in Cart)onEvents.h. II the Edit 
menu does not work right for a standard Toolbox text field, this is 
probably whafs wrong. We used to have a really slimy mechanism 
in place Lo clo this behind the app’s !>ack. On Mac OS X, lhai 
mechanism is gone, so we need a little ax operation fnm your 
application so wc can all play in the same menu sumikix. 

One tiling to keep in mind — do nol assume a command came 
from a menu! Always check the aurilxites of tiie command to make 
sure the kHICommandFromMenu bit Ls set. If not, ckm'L try to access 
the menu.menuRef or menu.menultemlndex fields. Remember that 
armmands can come from controls, and Apple will k adjusting this 
structure in the future to accommodate that. 

Modality 

There are times in your application where you need to pul up 
a irnxlal dialog, i.e. it disallows clicks in oilier windows. Usually, 
when in tills state, the menu bar is disabled except for a lew choice 
menu items. In the pass, you would have had to either use 
ModalDialog, or mil your own modal event loop. 

The CEM offers a new way to go about this- 
RunAppModalLoopForWindow, Like RunApplicationEventLoop, once 
called, your application stays inside this API until a corresponding 
oil to QuilAppModalLoopForWindow is made. Once you enter this 
state, the menu bar automatically disables. Depending on what 
command handlers you have installed for the window, you can 
enable certain menu items within your modal context. For 
example, even though the menu bar is disabled, if you tab into a 
text field, the Edit menu will react as it should, handling 
kEventCommandUpdateStatus events that are sent to it. 


Usually when you implement something like this, you install an 
event handler lor the window to capture command events. Inside 
this handler is where you would end up calling 
QuitAppModalLoopForWindow. lasting 5 shows an example of creating 
a dialog from a nib file and running ii modally. We are essentially 
asking the user a yes or no question, and the result of the interaction 
with tile user determines whether we return tme or false. 

lasting 5: Running a dialog modally 

Boolean 

Cnnf 1 rmActivateSelfilest roct (} 
l 

iHKSbRef nibRef; 

lSvent.TypeSpsc oadEvent = 

j kKventClassCoiranand, kEveiitCu^^dFrocess J: 

VindowRef window; 

QSStatus err; 

EventHand1e rUFF handler; 

Gonf 1 rmDa t a cist a; 

Boolean result * false; 

// (frt the nih rcfamaraivaie the window from it.unit release the nib afcrcncc 

err - CreateNibReferenee( CFSTRf "Main" L MiibHef ); 
require_noerr( err. GnutOpenNib 

err = CreateWindowFromNibt uibRef, 

CFS*m( "ActivateSelfOesi mrr* ). ^window ); 
require_noer r ( err * CantCreateWiudow ); 

DisposeNibReferencot tiibRef ); 


// Install :tn event handler to listen to command events tor the window. 

//This is tile only Lyix: oT event wc care about! 

//Wc |ms data needed by our handler in to our cull to InNtMWintkMvEwnUiwKliet 
// I ictv wc pass the window rtf. is well as tin- uupt hmlt-in which tells us 
// whether Oh: sdkksTmii fflftdrafttettt slioukl lie xlivated. 

dqta.emifiri&ed ~ false; 
data.window - window: 

handler = NewEveuTHatidlerUPP( SelfBestrucUtaadior ); 
InstallWirdowKvmrRandlerC window, handier. 1. 

RcmdEveriL, fcdara, MULL ); 

// Move the window into pttiiiun ami si row it 

Reposi t EonWindowt window, NULL, 

kWi ndowAlertPofiitionOnMainS c r eon ); 

ShowVludowC window }; 

// Mow run the window mothlly.Vfc wilt remain irudde 
// HvinAppMc mMIjx ipRwWindow until the Quit. . call is made 
// in our ErascDtsid bndkr mi nine. 

KLUiAppModiilLoopForWindow( window ); 

// We Ye dbad Get our resuic dispose the window, and exit 

result = data.eonfirmed; 

Dispo^eWindowC window ); 

UiGponf , iEventHandIerUPP( handler ); 

return result: 

CantCreateVindow: 

DLsposeHibRefereueet nibkef J; 

CantOpejiNib: 

rctirrn result; 

I 
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If you Iwk closely, you will see it’s extremely similar to our 
main function in our basic application we looked at earlier The only 
real difference is we have installed a window event handler on the 
window we create to handle command events. Jlie next listing 
shows a simple example of such a handler: 

listing 6: Our self-destruct modal dialog handler 

GSStatus 

SelfDestriiciHandloT (EventHandlerCal IRpf inCallRef. 

EventRef inKvent , 

void* iiiVserPata) 

1 

HI Command e ntd: 

GSStatus renult ~ eventNotHandiedErr; 

Conti rroData* Am a ~ (CorifirmData *1 inlfser Data; 


//Thr cliftu! ohjiTt for .i pmcvwi command event is tin- ItJCuiunumJ 
// Extract ii hm and switch off tfjc commantl JO 

GvtEventPararaeter{ inRvent h kEventParamDlreetQbjer.t* 
typelftCoBStinnd* NULL, sizeof( cmd }. NULL, fcrroH ); 

switch ( end.commandID ) 

* 

ease kHtCorauandUK: 

//ilic OK button w;ts clicked Suin' mK 1 into our magic boolean. 

<fata->cdnfinned “ Lme; 


// Stick a fork m us. we're doneTtminatc the call to 
// Riia\|?pMixyixx^«Wintkiw r and return mErr to inchoate 
// wc hreiifkif tills ctmunnnd. 

QuitAppHodairoopFarHiiidowt data->w±ndow ): 

result = noKrr: 

break; 

c asp kFrTCotnmtiTidCsncel; 

//The uscrchckcd cancel.Our data was passed in to us with 
// false set, but since we don't want to risk the si tip based (in 
// my assumptions, we set it to fisc explicitly! Wc then quit 
// Uk* modal loop and ntum noLrr to indicate liandlcd this event. 

data >confi treed ” false: 

0u3tAppModalLoopForVindowf dain >window ): 

result - noEtrr; 

break; 

1 

return result; 

I 

If you’re wondering where these commands are coming from, 
they are bring read in as part of the nib file. For any control in a nih, 
you can set a command ID for if. When the nib Is read in and the 
controls are created, any command ID you specified will 
automatically be set lor the control. In our example, if the 
kHICommandCancel or kHICommandOK commands arc received, we 
call QuitAppMocfalLocpFoiWindow, which terminates our modal loop, 

ThF. DIALOG WllAI? 

The interesting tiling with the examples in the last 
section is that you 11 notice that with the combination of nibs 
and commands, the Dialog Manager is obsolete. The only 
tiling we didn't cover is being able to access controls by 


control ID. This is something new in Carbon that allows you 
to get at your controls with a unique identifier. For dialog 
items using the Dialog Manager you would have typically 
used GetDialogltem or GetDialogltemAsControb passing the 
dialog item number of the item you were interested in. That 
has a major failing in that if you reorder your items, you need 
to change all your constants, as the dialog item number is 
just an index into the dialog item list. Control IDs allow 
position independence — it doesn't matter where the control 
is in the control hierarchy for a window, you can easily Find 
it with the control ID. If you move it, you’ll still find it with 
the same code. Interface Builder lets you assign IDs to 
controls so that when you instantiate an object from a nib, 
the control IDs are all set to go. 

The other thing the Dialog Manager has historically kept 
track of is the default and cancel items of a dialog. The 
default item is the item that would be liif by pressing enter 
or return, and the cancel item is the item which would be 
‘hit 1 by pressing command-period or escape on the keyboard. 
To replace that, we have introduced SetWindowDefaultButton 
and SetWindowCancelButton. The standard Toolbox event 
handlers for windows check for default and cancel button 
hits' like the Dialog Manager would. Again, Interface Builder 
lets you specify that a button is the default or cancel button. 

All of this means you can now lay out dialogs vviLh 
Interface Builder (which is really easy!), and run them with 
the Carbon Event Model, and you don't have Lo worry about 
Lhc Dialog Manager's idiosyncrasies from 1984, 

Owl My brain huris! 

Wow. That was a lot of information! But I think we 
covered all of the basic aspects of the Carbon Event Model 
and how they work. Now r you have a good foundation of 
knowledge upon which you can start building. In future 
articles, we can start moving into concrete examples and 
more esoteric aspects of all this. 

As you can see, It's a very exciting addition to the 
Toolbox. We see it as the piece that has been missing for too 
long which will allow the Toolbox to grow into something 
really amazing as we move forward. Any new functionality 
we add will generally involve some aspect of this new event 
system, so il T s important to understand it. 

As was evident from the examples, you can write a lot 
of application in very little code. In the future, we will he 
able Lo reduce that code even further, possibly to as little as 
3 lines of code to start up an application! We will also be able 
to add more functionality for free while still allowing your 
applications to alter behaviors, 1 encourage you all to start 
playing with this stuff and see what it can do. 

Its the beginning of a whole new era for Carbon application 
programming! 

Special thanks to Eric ScblegeJ f Guy Fullerton and Matt 

Ackeret for revieunng this article. HO 
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